API需求设计文档范本解读.docx

文档状态： 核准人： 核准日期： 1.5 API 需求文档 文档历史 修订日期 修订内容 修订人 2015.5.27 圈子api需求  目录 1 引言 5 1.1 编写目的 5 1.2 参考资料 5 1.3 常量定义 5 1.3.1 服务器地址 5 1.3.2 错误代码 5 1.3.3 性别 5 1.3.4 学校类型 6 1.3.5 用户角色 6 2 接口介绍 6 2.1 接口说明 6 2.2 接口协议 6 2.3 请求HTTP Header 7 2.4 请求参数 7 2.5 响应数据格式 7 2.6 身份认证 7 3 数据结构 8 3.1 基本类型定义 8 3.2 基本信息结构 8 3.2.1 图片URL信息 8 3.3 用户信息 8 3.3.1 老师用户信息 8 3.3.2 学生用户信息 9 3.4 圈子信息 9 3.4.1 圈子基础信息 9 3.4.2 圈子内容信息 9 3.4.3 圈子评论信息 10 4 API接口 10 4.1 班级圈 10 4.1.1 获取圈子列表 10 4.1.2 获取圈子主题 11 4.1.3 获取主题评论 12 4.1.4 点赞 12 4.1.5 在圈子发主题 12 4.1.6 给主题评论 13 1 引言 1.1 编写目的 统一对外接口，方便使用接口的开发者根据文档进行开发和调试 1.2 参考资料 术语说明 名称 说明 1.3 常量定义 1.3.1 服务器地址 API请求基地址：base_url， (请host设置为2) 1.3.2 错误代码 0表示成功，0失败代码。 代码 值 说明 NO_ERROR 0 无错误 INVALID_PARAMETER -1 请求参数错误 INVALID_STUDENT_ACCOUNT -2 学生代码无效 INVALID_PASSWORD -3 密码无效 1.3.3 性别 值 说明 0 女 1 男 1.3.4 学校类型 值 说明 0 小学五年制 1 小学六年制 2 初中三年制 3 初中四年制 4 高中 5 1.3.5 用户角色 值 说明 0 管理员 1 校长 2 老师 3 家长 4 学生 5 2 接口介绍 2.1 接口说明 此文档应包含所有手机客户端开发所需要调用的接口，但因文档水平以及设计周期问题，难免会有缺漏. 2.2 接口协议 所有接口遵循HTTP协议，根据接口的不同需选择GET或POST的调用方式，返回数据均为JSON格式 2.3 请求HTTP Header 2.4 请求参数 所有请求参数均应使用UTF-8然后URL Encoding方式编码。使用POST方式调用时，应指定Content-Type为“application/x-www-form-urlencoded”。 2.5 响应数据格式 所有接口返回数据均为JSON格式，如无特殊说明，均为如下数组形式 Key 说明 code 整数，成功或失败代码，参见结果代码 msg 字符串，错误信息 data JSON Object（key-value对），根据接口不同，data数据不同，每个接口的具体说明。 其他 其他数据，会在每个接口给出具体说明 { code: 1, msg: 错误信息, data: [{ code: 1, msg: 错误信息 },{ code: 1, msg: 错误信息 }] } 2.6 身份认证 当用户登陆或注册成功时，服务器端返回客户端身份ID”token” 登录或注册成功后，访问身份认证的API时，客户端需要传递用户身份，否则服务器端返回错误代码。 3 数据结构 3.1 基本类型定义 名称 类型 说明 boolean 布尔型 0或false，1或true int 32位有符号整数 long 64位有符号整数 float 32位浮点数 timestamp 系统时间戳 从格林威治时间1970年1月1日零时到现在的秒数。负值表示1970年往前的秒数。 string 字符串 3.2 基本信息结构 3.2.1 图片URL信息 字段 变量名 类型 说明 original 原始图片 string large 大尺寸图片 string middle 中等尺寸图片 string small 小尺寸图片 string 3.3 用户信息 3.3.1 老师用户信息 字段 变量名 类型 说明 userID 用户ID String userName 姓名 String 账号 密码 性别 性别 自我介绍 string 人物头像 图片URL信息 3.3.2 学生用户信息 字段 变量名 类型 说明 用户ID 姓名 账号 密码 性别 性别 自我介绍 string 人物头像 图片URL信息 3.4 圈子信息 3.4.1 圈子基础信息 字段 变量名 类型 说明 id 圈子标识 name 圈子名称