API需求设计文档范本.docx

API需求设计文档范本.docx

《API需求设计文档范本.docx》由会员分享，可在线阅读，更多相关《API需求设计文档范本.docx（18页珍藏版）》请在冰豆网上搜索。

API需求设计文档范本

文档状态：

核准人：

核准日期：

需求文档

文档历史

修订日期

修订内容

修订人

圈子需求

引言

编写目的

参考资料

常量定义

服务器地址

错误代码

性别

学校类型

用户角色

接口介绍

接口说明

接口协议

请求

请求参数

响应数据格式

身份认证

数据结构

基本类型定义

基本信息结构

图片信息

用户信息

老师用户信息

学生用户信息

圈子信息

圈子基础信息

圈子内容信息

圈子评论信息

接口

班级圈

获取圈子列表

获取圈子主题

获取主题评论

点赞

在圈子发主题

给主题评论

1引言

1.1编写目的

统一对外接口，方便使用接口的开发者根据文档进行开发和调试

1.2参考资料

术语说明

名称

说明

1.3常量定义

1.3.1服务器地址

请求基地址：

，（请设置为）

1.3.2错误代码

表示成功，<失败代码。

代码

值

说明

无错误

请求参数错误

学生代码无效

密码无效

1.3.3性别

值

说明

女

男

1.3.4学校类型

值

说明

小学五年制

小学六年制

初中三年制

初中四年制

高中

1.3.5用户角色

值

说明

管理员

校长

老师

家长

学生

2接口介绍

2.1接口说明

此文档应包含所有手机客户端开发所需要调用的接口，但因文档水平以及设计周期问题，难免会有缺漏.

2.2接口协议

所有接口遵循协议，根据接口的不同需选择或的调用方式，返回数据均为格式

2.3请求

2.4请求参数

所有请求参数均应使用然后方式编码。

使用方式调用时，应指定为“”。

2.5响应数据格式

所有接口返回数据均为格式，如无特殊说明，均为如下数组形式

说明

整数，成功或失败代码，参见结果代码

字符串，错误信息

（对），根据接口不同，数据不同，每个接口的具体说明。

其他

其他数据，会在每个接口给出具体说明

{

"":

"",

"":

"错误信息",

"":

[{"":

"",

"":

"错误信息"

},{"":

"",

"":

"错误信息"

}]

}

2.6身份认证

当用户登陆或注册成功时，服务器端返回客户端身份””

登录或注册成功后，访问身份认证的时，客户端需要传递用户身份，否则服务器端返回错误代码。

3数据结构

3.1基本类型定义

名称

类型

说明

布尔型

或，或

位有符号整数

位有符号整数

位浮点数

系统时间戳

从格林威治时间年月日零时到现在的秒数。

负值表示年往前的秒数。

字符串

3.2基本信息结构

3.2.1图片信息

字段

变量名

类型

说明

原始图片

大尺寸图片

中等尺寸图片

小尺寸图片

3.3用户信息

3.3.1老师用户信息

字段

变量名

类型

说明

用户

姓名

账号

密码

性别

性别

自我介绍

人物头像

图片信息

3.3.2学生用户信息

字段

变量名

类型

说明

用户

姓名

账号

密码

性别

性别

自我介绍

人物头像

图片信息

3.4圈子信息

3.4.1圈子基础信息

字段

变量名

类型

说明

圈子标识

圈子名称

班主任

用户信息数组

任课教师

用户信息数组

成员信息数组

用户信息数组

3.4.2圈子内容信息

字段

变量名

类型

说明

内容标识

内容标题

内容图片

发布者信息

用户信息

发布时间

点赞数量

点赞者信息

用户信息数组

评论数

3.4.3圈子评论信息

字段

变量名

类型

说明

评论标识

评论时间

评论内容

评论者信息

用户信息数组

发布时间

4接口

4.1班级圈

请求基地址：

，

参数格式实例（以保存圈子用户为例）：

{

:

"李四",

}

实例（以获取圈子列表为例）：

4.1.1获取圈子列表

:

{}

调用方式

字段

变量名

类型

说明

可空

用户标识

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

圈子信息数组

[

{

"":

"",

"":

"":

"",

"":

"":

"":

[],

"":

[],

"":

[],

"":

},

{

"":

"",

"":

"":

"",

"":

"",

"":

"",

"":

[],

"":

[],

"":

[],

"":

},

{

"":

"",

"":

"":

"",

"":

"",

"":

"":

[],

"":

[],

"":

[],

"":

}

]

4.1.2获取圈子主题

:

{}

调用方式

字段

变量名

类型

说明

可空

圈子标识

页数

默认第一页

每页数量

默认条

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

主题信息数组

内容总数

[

{

"":

"",

"":

"":

"",

"":

"测试",

"":

"":

"":

{

"":

"李四",

"":

""

},

"":

[],

"":

[],

"":

}

]

4.1.3获取主题评论

:

{}

调用方式

字段

变量名

类型

说明

可空

主题的标识

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

评论信息数组

{

"":

"",

"":

"":

"",

"":

"测试",

"":

{

"":

"",

"":

"":

"",

"":

"",

"":

"李四",

"":

"":

[],

"":

},

"":

"":

"":

}

4.1.4点赞

:

{}{}

调用方式

字段

变量名

类型

说明

可空

内容标识

点赞人标识

返回说明

{

"":

"",

"":

"":

"",

"":

"":

"":

"":

}

4.1.5在圈子发主题

:

{}{}

调用方式

字段

变量名

类型

说明

可空

圈子标识

圈子发表人标识

内容

图片

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

主题信息数组

{

"":

"",

"":

"":

"",

"":

"测试",

"":

"":

"":

"":

[],

"":

[],

"":

}

4.1.6给主题评论

:

{}

调用方式

字段

变量名

类型

说明

可空

内容

图片路径

圈子信息

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

评论信息数组

{

"":

"",

"":

"":

"",

"":

"测试",

"":

{

"":

"",

"":

"":

"",

"":

"",

"":

"李四",

"":

"":

[],

"":

},

"":

"":

"":

}

4.1.7获取圈子用户

:

{}

调用方式

字段

变量名

类型

说明

可空

圈子标识

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

用户信息数组

{"":

"",

"",

"":

"",

"",

"",

"":

[

{"":

"",

"",

"":

"",

"":

"",

"":

"",

""

}

],

"":

[],

"":

[],

""

}

4.1.8添加圈子用户

:

调用方式

字段

变量名

类型

说明

可空

用户标识

圈子标识

用户名称

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

主键

创建时间

是否删除

代表未删除，代表已删除

用户标识

用户名称

圈子信息

{

"":

"",

"":

"":

"",

"":

"",

"":

"李四",

"":

"":

[],

"":

}

4.1.9移除圈子用户

:

{}

调用方式

字段

变量名

类型

说明

可空

圈子用户标识

用户标识数组

返回说明

：

多维数组，每个数组元素如下

字段

变量名

说明

用户信息数组

{

"":

"",

"":

"":

"",

"":

"",

"":

"李四",

"":

"":

[],

"":

}