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

版本管理	修改记录
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"} // 其他原因导致失败