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 |
） |
|
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 |
） |
|
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 |
） |
|
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 |
） |
|
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, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） 道题） |
|
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, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） 道题） |
|
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, //标签名，用于通过标签查询问题（可选，没有的话就随便给一些） 道题） |
|
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, 道题） |
|
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"} // 其他原因导致失败 |
BugPhobia准备篇章：Beta阶段前后端接口文档的更多相关文章
- [API]使用Blueprint来高雅的编写接口文档 前后端api文档，移动端api文档
网址:http://apiary.io/ 介绍:一款非常强大的前后端交互api设计编辑工具(编辑器采用Markdown类似的描述标记,非常高效),高颜值的api文档,还能生成多种语言的测试代码. 中文 ...
- vue菜鸟从业记：公司项目里如何进行前后端接口联调
最近我的朋友王小闰进入一家新的公司,正好公司项目采用的是前后端分离架构,技术栈是王小闰非常熟悉的vue全家桶,后端用的是Java语言. 在前后端开发人员碰面之后,协商确定好了前端需要的数据接口(扯那么 ...
- 前后端分离之【接口文档管理及数据模拟工具docdoc与dochelper】
前后端分离的常见开发方式是: 后端:接收http请求->根据请求url及params处理对应业务逻辑->将处理结果序列化为json返回 前端:发起http请求并传递相关参数->获取返 ...
- RAP, 高效前后端联调框架，接口文档管理工具
RAP通过GUI工具帮助WEB工程师更高效的管理接口文档,同时通过分析接口结构自动生成Mock数据.校验真实接口的正确性,使接口文档成为开发流程中的强依赖.有了结构化的API数据,RAP可以做的更多, ...
- SpringBoot集成Swagger（Swagger的使用），生成接口文档，方便前后端分离开发
首先上一张成果图. 1.Maven依赖 <dependency> <groupId>io.springfox</groupId> <artifactId&g ...
- Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档
前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对于开发人员来说,编写接口文档 ...
- Java | Spring Boot Swagger2 集成REST ful API 生成接口文档
Spring Boot Swagger2 集成REST ful API 生成接口文档 原文 简介 由于Spring Boot 的特性,用来开发 REST ful 变得非常容易,并且结合 Swagg ...
- Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求，简单请求)、自动生成接口文档)
一.Django中的缓存: 前戏: 在动态网站中,用户所有的请求,服务器都会去数据库中进行相应的增,删,查,改,渲染模板,执行业务逻辑,最后生成用户看到的页面. 当一个网站的用户访问量很大的时候,每一 ...
- Asp.Net Core 轻松学系列-5利用 Swagger 自动生成接口文档
目录 前言 结语 源码下载 前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对 ...
随机推荐
- BI之报表测试总结
报表测试总结: 1.测试准备工作: 数据准备 保证足够多的有效数据 清楚报表中涉及到的算法.公式 清楚业务功能接口 2.报表测试点 基本测试点:界面.控件.格式.布局.明显的数据错误.js报错.报表标 ...
- C#只能lock 引用类型的值 （转载）
Lock: C#只能lock 引用类型的值,如果lock一个int, bool,编译器会报错. 当一个互斥锁已被占用时,在同一线程中执行的代码仍可以获取和释放该锁.但是,在其他线程 ...
- Eclipse设置格式化每行字符的长度
Windows>>prefrence>>Java>>CodeStyle>>formatter>>edit>>line wrapp ...
- iOS 计算源码行数
如果要统计ios开发代码,包括头文件的,终端命令进入项目目录下,命令如下 1.列出每个文件的行数 find . -name "*.m" -or -name "*.h&qu ...
- springboot快速入门（五）——事务管理
一.入门 概念就不再赘述了,由于一般我们是通过service控制事务,这里给出注解式的示例: package com.example.demo; import com.example.demo.bea ...
- Java基础——注释规范
一.注释格式分类: 1.单行(single-line)注释://…… 2.块(block)注释:/*……*/ 3.文档注释:/**……*/ javadoc有如下: 二.加注释的场景: 1. 基本注释( ...
- [Oracle]ORA-01499的处理
如果出现 ORA-01499,说明 table 和 index之间的相互参照出了错: http://iderror.com/errors/oracle/oracle-db/ora-00900-to-o ...
- 10-[CSS]-盒模型：border，padding，margin
1.CSS盒子模型 HTML文档中的每个元素都被描绘成矩形盒子,这些矩形盒子通过一个模型来描述其占用空间,这个模型称为盒子模型. 盒子模型通过四个边界来描述:margin(外边距),border(边框 ...
- 4557: [JLoi2016]侦察守卫
4557: [JLoi2016]侦察守卫 链接 分析: 因为D比较小,所设状态f[i][j]表示子树i内,从i往下第j层及第j层以下都覆盖了的最小代价,g[i][j]表示覆盖完子树内所有点,还可以往上 ...
- Tomcat部署Web应用
在Tomcat中部署Web有三种方法: 1,可以将Web应用文件直接复制到webapps目录下,也可以将Web应用打成war包放到webapps目录下,tomcat会自动解开war包,并在webapp ...