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":"[email protected]", "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"} // 其他原因导致失败 |