API需求设计文档范本

1、文档状态：核准人：核准日期：1.5 API需求文档文档历史修订日期修订内容修订人2015.5.27圈子api需求目录1引言51.1编写目的51.2参考资料51.3常量定义51.3.1服务器地址51.3.2错误代码51.3.3性别51.3.4学校类型61.3.5用户角色62接口介绍62.1接口说明62.2接口协议62.3请求HTTP Header72.4请求参数72.5响应数据格式72.6身份认证73数据结构83.1基本类型定义83.2基本信息结构83.2.1图片URL信息83.3用户信息83.3.1老师用户信息83.3.2学生用户信息93.4圈子信息93.4.1圈子基础信息93.4.2圈子内容

2、信息93.4.3圈子评论信息104API接口104.1班级圈104.1.1获取圈子列表104.1.2获取圈子主题114.1.3获取主题评论124.1.4点赞124.1.5在圈子发主题124.1.6给主题评论13221 引言1.1 编写目的统一对外接口，方便使用接口的开发者根据文档进行开发和调试1.2 参考资料术语说明名称说明1.3 常量定义1.3.1 服务器地址API请求基地址：base_url，http:/tp.teem- (请host设置为2)1.3.2 错误代码0表示成功，<0失败代码。代码值说明NO_ERROR0无错误INVALID_PARAMETER-1请求

3、参数错误INVALID_STUDENT_ACCOUNT-2学生代码无效INVALID_PASSWORD-3密码无效1.3.3 性别值说明0女1男1.3.4 学校类型值说明0小学五年制1小学六年制2初中三年制3初中四年制4高中51.3.5 用户角色值说明0管理员1校长2老师3家长4学生52 接口介绍2.1 接口说明此文档应包含所有手机客户端开发所需要调用的接口，但因文档水平以及设计周期问题，难免会有缺漏.2.2 接口协议所有接口遵循HTTP协议，根据接口的不同需选择GET或POST的调用方式，返回数据均为JSON格式2.3 请求HTTP Header2.4 请求参数所有请求参数均应使用UTF-8

4、然后URL Encoding方式编码。使用POST方式调用时，应指定Content-Type为“application/x-www-form-urlencoded”。2.5 响应数据格式所有接口返回数据均为JSON格式，如无特殊说明，均为如下数组形式Key说明code整数，成功或失败代码，参见结果代码msg字符串，错误信息dataJSON Object（key-value对），根据接口不同，data数据不同，每个接口的具体说明。其他其他数据，会在每个接口给出具体说明 "code": "1","msg": "错误信息"

5、;,"data": "code": "1","msg": "错误信息","code": "1","msg": "错误信息" 2.6 身份认证当用户登陆或注册成功时，服务器端返回客户端身份ID”token” 登录或注册成功后，访问身份认证的API时，客户端需要传递用户身份，否则服务器端返回错误代码。3 数据结构3.1 基本类型定义名称类型说明boolean布尔型0或false，1或trueint32位有符号整数long

6、64位有符号整数float32位浮点数timestamp系统时间戳从格林威治时间1970年1月1日零时到现在的秒数。负值表示1970年往前的秒数。string字符串3.2 基本信息结构3.2.1 图片URL信息字段变量名类型说明original原始图片stringlarge大尺寸图片stringmiddle中等尺寸图片stringsmall小尺寸图片string3.3 用户信息3.3.1 老师用户信息字段变量名类型说明userID用户IDStringuserName姓名String账号密码性别性别自我介绍string人物头像图片URL信息3.3.2 学生用户信息字段变量名类型说明用户ID姓名账

7、号密码性别性别自我介绍string人物头像图片URL信息3.4 圈子信息3.4.1 圈子基础信息字段变量名类型说明id圈子标识name圈子名称班主任用户信息数组任课教师用户信息数组成员信息数组用户信息数组3.4.2 圈子内容信息字段变量名类型说明id内容标识content内容标题imgPath内容图片userID发布者信息用户信息createDate发布时间点赞数量commenter点赞者信息用户信息数组评论数3.4.3 圈子评论信息字段变量名类型说明id评论标识createDate评论时间content评论内容commter评论者信息用户信息数组发布时间4 API接口4.1 班级圈API请求

8、基地址：url，s参数json格式实例(以保存圈子用户为例)： userName:"李四", userID:66666, circleID:8a21838b4d8db258014d8db4d4080000,URL实例(以获取圈子列表为例)：9:10001/circleinfo/circleuser/66666/circles4.1.1 获取圈子列表URL:9:10001/circleinfo/circleuser/userID/circles调用方式get字段变量名类型说明可空userID用户标识StringN返回说明data：多维数

9、组，每个数组元素如下字段变量名说明圈子信息数组 "id": "8a21838b4d8db258014d8db4d4080000", "createDate": 1432601547733, "isDel": "1", "name": null, "img": null, "users": , "orgs": , "messages": , "new": false , &quo

10、t;id": "297ed94b4d7b043c014d7b046a820000", "createDate": 1432287996506, "isDel": "1", "name": "123", "img": "123123", "users": , "orgs": , "messages": , "new": false , "i

11、d": "297ed94b4d995b1e014d995bcc3b0004", "createDate": 1432797029621, "isDel": "0", "name": "123,img=456", "img": null, "users": , "orgs": , "messages": , "new": false 4.1.2 获取圈子主题URL:ht

12、tp:9:100001/circleinfo/messageinfo/circleID/messages调用方式get字段变量名类型说明可空circleID圈子标识StringN页数默认第一页Y每页数量默认10条Y返回说明data：多维数组，每个数组元素如下字段变量名说明主题信息数组内容总数 "id": "8a2182204d9988d0014d998c71ff0000", "createDate": 1432800227788, "isDel": "1", "co

13、ntent": "测试1", "imgPath": null, "circle": null, "circleUser": "userName": "李四", "userID": "8a2182204d9820a1014d982258810001" , "comments": , "likes": , "new": false 4.1.3 获取主题评论URL:10.1

14、61.3.99:10001/circleinfo/comments/commentID调用方式get字段变量名类型说明可空commentID主题的标识StringN返回说明data：多维数组，每个数组元素如下字段变量名说明评论信息数组 "id": "8a2182204d99be38014d99bee7ae0000", "createDate": 1432803534713, "isDel": "1", "content": "测试1", "com

15、menterUserVO": "id": "8a2182204d9820a1014d982258810001", "createDate": 1432776491043, "isDel": "1", "userID": "66666", "userName": "李四", "circle": null, "messages": , "new": f

16、alse , "deleterID": null, "message": null, "new": false4.1.4 点赞URL:9:10001/circleinfo/like/userID/circleID调用方式Post字段变量名类型说明可空内容标识N点赞人标识N返回说明 "id": "8a2182204dadc36b014dadc3ab910000", "createDate": 1433139391357, "isDel":

17、 "1", "commenter": 0, "deleteuser": null, "message": null, "new": false4.1.5 在圈子发主题URL:9:10001/circleinfo/message/circleID/userID调用方式Post字段变量名类型说明可空circleID圈子标识StringNuserID圈子发表人标识StringNimgPath内容StringNcontent图片StringY返回说明data：多维数组，每

18、个数组元素如下字段变量名说明主题信息数组 "id": "8a2182204d9988d0014d998c71ff0000", "createDate": 1432800227788, "isDel": "1", "content": "测试1", "imgPath": null, "circle": null, "circleUser": null, "comments": ,

19、 "likes": , "new": false4.1.6 给主题评论URL:9:10001/circleinfo/comments/circleID调用方式get字段变量名类型说明可空内容图片路径commentID圈子信息IDStringN返回说明data：多维数组，每个数组元素如下字段变量名说明评论信息数组 "id": "8a2182204d99be38014d99bee7ae0000", "createDate": 1432803534713, "isDel&

20、quot;: "1", "content": "测试1", "commenterUserVO": "id": "8a2182204d9820a1014d982258810001", "createDate": 1432776491043, "isDel": "1", "userID": "66666", "userName": "李四",

21、 "circle": null, "messages": , "new": false , "deleterID": null, "message": null, "new": false4.1.7 获取圈子用户URL:9:10001/circles/circleuser/circleID调用方式GET字段变量名类型说明可空圈子标识N返回说明data：多维数组，每个数组元素如下字段变量名说明用户信息数组"id":"8a2183

22、8b4d8db258014d8db4d4080000","createDate":1432601547733,"isDel":"1","name":null,"img":null,"users":"id":"8a2182204d94a64a014d94aa88ea0000","createDate":1432718313682,"isDel":"1","us

23、erID":"123","userName":"zhangsan","new":false,"orgs":,"messages":,"new":false4.1.8 添加圈子用户URL:9:10001/circleinfo/circleuser调用方式Post字段变量名类型说明可空useID用户标识StringNcircleID圈子标识StringNuserName用户名称StringN返回说明data：多维数组，每个数组元素如下字段变量名说明id主键createDate创建时间isD