BugPhobia准备篇章：Beta阶段前后端接口文档

0x00：序言

Two strangers fell in love,

Only one knows it wasn’t by chance.

To the searching tags, you may well fall in love with http:// 10.2.26.67

Github地址：Beta阶段前后端接口定义说明.md

 

版本管理	修改记录
V1.0	Beta阶段前后端接口文档一稿整理完成，记录用户、标签（含推荐）、搜索和问答部分的主要接口

 

0x01 ：接口定义说明

接口定义描述	具体样例说明
Particular Scopes（URL）：通过URL描述基本的属性或关系	ü  /users/{id}/notifications ü  /question/add
Methods（HTTPS Protocol）：描述服务器的交互方法	ü  GET, POST, PUT, DELETE
Arguments（Requires）：API本身所需的参数	ü  private_information ü  write/read_access
Return：API本身返回的文本返回值	ü  {"body":,"is_unrea":,"post_id":}

 

特别说明：Django框架依据cookies来管理用户状态，因此对于Android端的前端开发的团队（Dream：http://www.cnblogs.com/groupofdream/），必须启用cookies进行管理；经过调研，Android能够依据HttpClient自动管理cookies，再查阅调研后，将有效提升前端本身的开发效率

 

0x02 ：用户管理说明

 

0x0200：用户登录

URL	/accounts/login
Method	POST
Argument	ü  username 用户名 ü  password 密码
Return	ü  成功时 {"state":"ok"} ü  密码错误时 {"state":"failed"} ü  无此用户时 {"state":"missing"}

 

0x0204：用户注销

URL	/accounts/logout
Method	POST
Argument	——
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

 

0x0208：设定用户信息（Login Required）

URL	/accounts/updateprofile
Method	POST
Argument	ü  email 邮件地址 ü  realname 真实姓名 ü  description 一句话自我介绍
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

 

0x020c：获取用户信息（Login Required）

URL	/accounts/userinfo
Method	GET
Argument	——
Return	ü  成功时 {"state":"ok",         "email":"example@example.com",         "creation_time":UNIXTimestamp,         "realname":"example_real_name",         "description":"I'm a example",         "credit":123,         "forgottime":UNIXTimestamp,         "download":123} ü  失败时 {"state":"failed"}

 

0x03：标签（TAG）管理说明

 

0x0300：关注TAG（Login Required）

URL	/accounts/liketag
Method	GET
Argument	ü  tag 标签名
Return	ü  成功时 {       "state":"ok",       "tags": [         {           "tagname":"name1",           "count": 123,           "excerpt": "name1 is a balabala..."         }，         {           "tagname":"name2",           "count": 222,           "excerpt": "name2 is a balabala..."         }       ] } 失败时 {"state":"failed"}

 

0x0304：取消关注TAG（Login Required）

URL	/accounts/disliketag
Method	GET
Argument	ü  tag 标签名
Return	ü  成功时 {       "state":"ok",       "tags": [         {           "tagname":"name1",           "count": 123,           "excerpt": "name1 is a balabala..."         }，         {           "tagname":"name2",           "count": 222,           "excerpt": "name2 is a balabala..."         }       ] } 失败时 {"state":"failed"}

 

0x0308：获取TAGS

URL	/accounts/tags       {*依据count降序获取标签*}
Method	GET
Argument	ü  PageNum 前端所显示的问题的页数（默认此值为10）
Return	ü  成功时 {       "state":"ok",       "tags": [         {           "tagname":"name1",           "count": 123,           "excerpt": "name1 is a balabala..."         }，         {           "tagname":"name2",           "count": 222,           "excerpt": "name2 is a balabala..."         }       ]     } ü  失败时 {"state":"failed"}

 

0x030c：推荐TAGS

URL	/recommended/tags
Method	GET
Argument	ü  PageNum 前端所显示的问题的页数（默认此值为10）
Return	ü  成功时 {       "state":"ok",       "tags": [         {           "tagname":"name1",           "count": 123,           "excerpt": "name1 is a balabala..."         }，         {           "tagname":"name2",           "count": 222,           "excerpt": "name2 is a balabala..."         }       ]       } ü  失败时 {"state":"failed"}

 

0x0310：推荐QUESTIONS

URL	/recommended/questions
Method	GET
Argument	ü  PageNum 前端所显示的问题的页数（默认此值为10）
Return	ü  成功时 {       "state":"ok",       "questions": [         {           "question_id":123,           "title": "my question is a balabala...",           "content": "hi,..."           "uid": "user id" //提问者id           "uname": "user name"//提问者姓名           "shortAns": "answer is balabala"//问题的简短回答（如果已被选中“最佳答案”）           "views": 123 //访问数           "replies": 1 //回复数           "solved": true //是否已采纳“最佳答案           "PostDateTime": UNIXTimestamp//提出问题的时间         },         ...       ]       } ü  失败时 {"state":"failed"}

 

0x0314：推荐ANSWERS

URL	/recommended/answers
Method	GET
Argument	ü  PageNum 前端所显示的问题的页数（默认此值为10）
Return	ü  成功时 {       "state":"ok",       "answers": [         {           "question_id":123,           "answer_id":111,           "count": 123,           "content": "hi,...",           "uid": 66666666,           "uname": "answer's name",           "title": "answer title",           "Qtitle": //该回答所属问题的标题，用于显示“用户回答过的问题”时           "views": 222,           "votes": 123,           "PostDateTime": UNIXTimestamp, //回答问题的时间           "IsBestAns": true//判断该answer是否是所属问题的最佳answer         }       ]       } ü  失败时 {"state":"failed"}

 

0x04：搜索管理说明

 

URL	/search/query
Method	GET
Argument	ü  query_content 待搜索的内容或tag
Return	ü  成功时 {       "tag_description":"Java is an object-orinented....",       "query_content":"Java",       "question_list":[         {           "body":"balabala",           "creation_date":"2014 Oct",           "score":44,           "tags_name":"Java",           "url":"http://abc",           "view_count":2,             ......         },           {            ......         }       ]       } ü  失败时 query_content不在request.GET中，返回{"state":"invalid"}，无法获得tag的id:{"state":"failed","query_content":"Java"},计划启用SOLR搜索

 

0x05：问答管理说明

 

0x0500：未解决问题

URL	/question/getUnservedQuestions
Method	GET
Argument	ü  tag, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） ü  pageNum, //前端所显示问题的页数（现在每页显示10道题）
Return	ü  成功时 {          "state":"ok",       "questions": [         {           "question_id":123,           "title": "my question is a balabala...",           "content": "hi,..."           "uid": "user id" //提问者id           "uname": "user name"//提问者姓名           "shortAns": "answer is balabala"//问题的简短回答（如果已被选中“最佳答案”）           "views": 123 //访问数           "replies": 1 //回复数           "solved": true //是否已采纳“最佳答案           "PostDateTime": UNIXTimestamp//提出问题的时间         },         ...       ] } ü  失败时 {"state":"failed"}

特别说明：用户未登录，最多只返回10道题，若用户已登录，问题数由pageNum或已爬取的问题总数决定。登录与否通过Cookies来判断，利用Django自带的机制即可，无需额外传参

 

0x0504：热门问题

URL	/question/getHotQuestions
Method	GET
Argument	ü  tag, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） ü  pageNum, //前端所显示问题的页数（现在每页显示10道题）
Return	ü  成功时 {          "state":"ok",       "questions": [         {           "question_id":123,           "title": "my question is a balabala...",           "content": "hi,..."           "uid": "user id" //提问者id           "uname": "user name"//提问者姓名           "shortAns": "answer is balabala"//问题的简短回答（如果已被选中“最佳答案”）           "views": 123 //访问数           "replies": 1 //回复数           "solved": true //是否已采纳“最佳答案           "PostDateTime": UNIXTimestamp//提出问题的时间         },         ...       ] } ü  失败时 {"state":"failed"}

 

0x0508：“我”提出的问题（Login Required）

URL	/question/getUnservedQuestions
Method	GET
Argument	ü  tag, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） ü  pageNum, //前端所显示问题的页数（现在每页显示10道题）
Return	ü  成功时 {          "state":"ok",       "questions": [         {           "question_id":123,           "title": "my question is a balabala...",           "content": "hi,..."           "uid": "user id" //提问者id           "uname": "user name"//提问者姓名           "shortAns": "answer is balabala"//问题的简短回答（如果已被选中“最佳答案”）           "views": 123 //访问数           "replies": 1 //回复数           "solved": true //是否已采纳“最佳答案           "PostDateTime": UNIXTimestamp//提出问题的时间         },         ...       ] } ü  失败时 {"state":"failed"}

 

0x050c：“我”发表的问题（Login Required）

URL	/question/getMyAnswers
Method	GET
Argument	ü  uid, ü  pageNum, //前端所显示问题的页数（现在每页显示10道题）
Return	ü  成功时 {         "state":"ok",               "answers": [         {           "question_id":123,           "answer_id":111,           "count": 123,           "content": "hi,...",           "uid": 66666666,           "uname": "answer's name",           "title": "answer title",           "Qtitle": //该回答所属问题的标题，用于显示“用户回答过的问题”时           "views": 222,           "votes": 123,           "PostDateTime": UNIXTimestamp, //回答问题的时间           "IsBestAns": true//判断该answer是否是所属问题的最佳answer         }，         ...       ] } ü  失败时 {"state":"failed"}

 

0x0510：获得某道问题的详细信息

URL	/question/getQuestionById
Method	GET
Argument	ü  question_id      //问题的id
Return	ü  成功时 {         "state":"ok",               "question": {             "question_id":123,             "title": "my question is a balabala...",             "content": "hi,..."             "uid": "user id" //提问者id             "uname": "user name"//提问者姓名             "shortAns": "answer is balabala"//问题的简短回答（如果已被选中“最佳答案”）             "views": 123 //访问数             "replies": 1 //回复数             "solved": true //是否已采纳“最佳答案             "PostDateTime": UNIXTimestamp//提出问题的时间           },               "answers": [           {             "question_id":123,             "answer_id":111,             "count": 123,             "content": "hi,...",             "uid": 66666666,             "uname": "answer's name",             "title": "answer title",             "Qtitle": //该回答所属问题的标题，用于显示“用户回答过的问题”时             "views": 222,             "votes": 123,             "PostDateTime": UNIXTimestamp, //回答问题的时间             "IsBestAns": true//判断该answer是否是所属问题的最佳answer           }，           ...         ],               "tags": [           {             "tagname":"name1",             "count": 123,             "excerpt": "name1 is a balabala..."           }，           {             "tagname":"name2",             "count": 222,             "excerpt": "name2 is a balabala..."           },           ...         ] } ü  失败时 {"state":"failed"}

 

0x0514：提问（Login Required）

URL	/question/addQuestion
Method	GET
Argument	ü  uid, ü  title, ü  content, ü  tags //各个tag用逗号分隔
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

 

0x0518：增加访问数

URL	/question/addView
Method	GET
Argument	ü  question_id      //问题的id
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

 

0x051c：选中最佳答案（Login Required）

URL	/question/solevdQuestion
Method	GET
Argument	ü  qid //问题的id ü  aid
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"denied"} // 没权限被拒绝 {"state":"failed"} // 其他原因导致失败

 

0x0520：点赞（Login Required）

URL	/question/giveVote
Method	GET
Argument	ü  answer_id
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

特别说明：判断用户对该答案是否点过赞，如果点过，赞数减一；如果没点过，赞数加一

 

0x0524：修改问题（Login Required）

URL	/question/modifyQuestion
Method	GET
Argument	ü  question_id ü  title, ü  content, ü  tags //各个tag用逗号分隔
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"denied"} // 没权限被拒绝 {"state":"failed"} // 其他原因导致失败

 

0x0528：删除问题（Login Required）

URL	/question/deleteQuestion
Method	GET
Argument	ü  question_id,
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"denied"} // 没权限被拒绝 {"state":"failed"} // 其他原因导致失败

 

0x052c：添加答案（Login Required）

URL	/question/addAnswer
Method	GET
Argument	ü  qid, ü  content //答案的内容
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"failed"}

 

0x0530：删除答案（Login Required）

URL	/question/deleteAnswer
Method	GET
Argument	ü  answer_id,
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"denied"} // 没权限被拒绝 {"state":"failed"} // 其他原因导致失败

 

0x0534：修改答案（Login Required）

URL	/question/modifyAnswer
Method	GET
Argument	ü  answer_id,
Return	ü  成功时 {"state":"ok"} ü  失败时 {"state":"denied"} // 没权限被拒绝 {"state":"failed"} // 其他原因导致失败