[精华版]知道OPEN API接口规范文档10_final
![[精华版]知道OPEN API接口规范文档10_final](https://img.360docs.net/imged/1rrak8alz6qbeklxc7j4qeot0vy206bk-d1.webp)
![[精华版]知道OPEN API接口规范文档10_final](https://img.360docs.net/imged/1rrak8alz6qbeklxc7j4qeot0vy206bk-a2.webp)
[精华版]知道OPEN API接口规范文档10_final 百度知道OPEN API接口规范文档V1.0
系统名称百度知道OPEN API服务接口
项目负责人
作者耿艳坤
文档提交日期 2010-08-26
百度在线网络技术,北京,有限公司
(版权所有,翻版必究)
修改记录
修改后 No 修改内容简介修改日期修改人版本号
1 1.0 百度知道OPEN API服务接口 2010-08-26 耿艳坤
目录
1 背
景 ..................................................................... .......................................... 5 2 规范适用对象说
明 ..................................................................... ..................... 5 3 名词解
释 ..................................................................... ................................... 5 4 请求数据包格式规
范 ..................................................................... .. (5)
4.1
URL .................................................................... .. (5)
4.2 参
数 ..................................................................... .. (6)
4.2.1 系统级参
数 ..................................................................... . (6)
4.2.2 业务级参数的通用约定 (6)
4.2.3 参数签名算法...................................................................... ...... 6 5 响应数据包格式规
范 ..................................................................... .. (7)
5.1 XML输出格
式 ..................................................................... . (7)
5.2 json输出格
式 ..................................................................... .. (8)
5.3 错误响应输出格
式 .....................................................................
........ 8 6 错误码定
义 ..................................................................... ............................... 9 7 API接口细则...................................................................... . (9)
7.1
baidu.zhidao.getQuestionList ........................................... . (9)
7.1.1 功能...................................................................... .. (9)
7.1.2 参数...................................................................... .. (9)
7.1.3 返回
值 ..................................................................... . (10)
7.2
baidu.zhidao.getQuestionSearch ......................................... .. (10)
7.2.1 功能...................................................................... . (10)
7.2.2 参数...................................................................... . (10)
7.2.3 返回
值 ..................................................................... . (11)
7.3
baidu.zhidao.getQuestionInfo ........................................... (11)
7.3.1 功能...................................................................... . (11)
7.3.2 参数...................................................................... . (11)
7.3.3 返回
值 ..................................................................... . (12)
7.4
baidu.zhidao.getQuestionAnswer ......................................... .. (12)
7.4.1 功能...................................................................... . (12)
7.4.2 参数...................................................................... . (13)
7.4.3 返回
值 ..................................................................... . (13)
7.5
baidu.zhidao.question................................................... .. (13)
7.5.1 功能...................................................................... . (13)
7.5.2 参数...................................................................... . (13)
7.5.3 返回
值 ..................................................................... . (14)
7.6
baidu.zhidao.answer .................................................... . (14)
7.6.1 功能...................................................................... . (14)
7.6.2 参数...................................................................... . (14)
7.6.3 返回
值 ..................................................................... ................14 8 第三方提供API接口细
则 ..................................................................... .........15 9 附件及参考资
料 ..................................................................... .. (16)
1 背景
本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。
2 规范适用对象说明
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的Open API。
3 名词解释
, 百度知道:
, API KEY:注册API合作时由百度的OPEN API平台分配的唯一标识一个应用的字符串～又
称应用公钥
, API SECRET:注册API合作时由百度的OPEN API平台分配的应用密钥～用于
平台与合作站
点之间通信时的参数签名
4 请求数据包格式规范
4.1 URL
按照百度Open API规范～百度知道OPEN API提供如下REST风格的HTTP接口: {query_string}
query_string由系统级参数部分和具体Open API调用参数部分组成～以
key1=value&key2=value2&…表示～对于采用POST请求的Open API～
query_string部分则是在POST请求体里。所有查询类的Open API接口既支持POST～也支持GET方式～提交类的OPEN API接口仅支持POST方式。
4.2 参数
4.2.1 系统级参数
以下参数是由百度Open API平台系统定义的～百度知道需要支持这些参数以
便接入该平台提供开放接口。百度知道采用应用授权认证接口方式～合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥api_secret。
表格 4-1 API系统级参数
参数名类型是否必需描述
api_key string 是注册应用时分配到的api key
采取baidu.zhidao.getQuestionList这method string 是样的命名空间方式
制定方法名
时间戳～系统时间的秒值,同个应用的不call_id uint 是同api请求的time
值应该是递增的, 用
于防replay攻击
format string 否响应包格式～可以是xml,默认,或json
API调用请求包的编码类型～支持UTF-8ie string 否和GBK
参数签名～对bd_sig外所有参数串的签bd_sig string 是名～包括业务级的参数。 4.2.2 业务级参数的通用约定
百度知道遵守百度Open API规范中业务级通用参数的约定。表格 4-2 业务级参数的通用约定
参数名类型描述
page_no Int 用于支持分页的api～默认为1～表示第几页
用于支持分页的api～表示每页返回多少条数据～默认以及page_size Int 上限为25
4.2.3 参数签名算法
参数签名生成算法采取如下方式,PHP版,～其它语言根据注释描述完成等同功能:
//param_array是key-value形式的参数数组～不包括api_secret密钥本身//secret是合作申请成功后分配的api_secret密钥
function generate_sig($param_array, $secret) {
$str = '';
//对param_array中的参数名称进行升序排序
ksort($param_array);
//按照如下格式转换数组为string格式
foreach ($param_array as $k=>$v) {
$str .= "$k=$v";
}
//string末端补充api_secret密钥
$str .= $secret;
//生成MD5为最终的数据签名
return md5($str);
}
注:密钥是百度知道分配给第三方应用的secret_key～该算法返回的结果便是系统级参数中的
bd_sig。
5 响应数据包格式规范
响应数据包的格式由调用时传递的format参数指定,默认为xml格式,～无论是xml格式还是
json格式～输出内容都是UTF-8格式。目前～百度知道目前支持xml、json格式。
5.1 XML输出格式
, 文档编码格式UTF-8
, 接口的返回数据中～数组对应的xml节点包含list=”true”属性～其子节点的标签名跟对应
的数据有联系～并且同个数组内的同级节点的标签名一致。例如表示问题标题列表对应的
xml输出可能为:
, 接口的返回数据中～对象类型和普通数据类型数据,string～int～double～bool,对应的
xml节点不包含list属性或者list属性值为false～节点标签名具有实际意义～与数据所
描述的信息相符。例如～表示问题的数据对应的xml输出为:
5.2 json输出格式
API调用时如果传递format参数为json,大小写不敏感,～则正常响应包符合
如下规范的json字符串:
, http响应头中的Content-Type指定为application/json, charset=utf-8 , 字符串编码格式是UTF-8
字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串 5.3 错误响
应输出格式
错误响应输出内容符合以下规范:
, 返回内容由error_code, error_msg, request_args这3个属性组成～分别
用于描述错误
码～错误信息～以及调用Open API时所传递的所有参数的信息。 ,
request_args属性是一个数组～由n个包含key和value属性的对象组成.getQuestionList接口时传递的参数api_key无效～例如～假设第三方应用调
用baidu.zhidao
则其对应的xml格式的错误响应包为如下格式:
Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串
6 错误码定义
百度开放知道OPEN API调用过程中可能会返回的错误码定义如下表所示: error_code error_msg Description
Success 0 成功
Unknown error 1 未知错误
Service temporarily unavailable 2 后端服务暂时不可用
Unsupported openapi method 3 Open api接口不被支持
应用对open api接口的调用请求数Open api request limit reached 4 达到上限
Unauthorized client IP address:%s 5 open api调用端的IP未被授权
Invalid parameter 100 参数无效或缺失
Invalid API key 101 Api key无效
Invalid call_id parameter 103 Call_id参数无效或已被使用过
Incorrect signature 104 签名无效
Too many parameters 105 参数过多
Unsupported signature method 106 参数签名算法未被平台所支持
No permission to access data 200 没有权限访问数据
No such application exists 900 应用不存在
Parameters format error 12001 必选参数格式错误
Answer for invalid question 12002 提交回答的问题生命已结束 7 API接口细则
以下接口返回数据均是以XML格式为demo，JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。
7.1 baidu.zhidao.getQuestionList
7.1.1 功能
基于百度知道分类ID获取对应分类下的问题列表
URL Demo:
;method=baidu.zhidao.getQuestionList
&call_id=1276418994&format=xml&bd_sig=sig-
result&cid=249&qstatus=0&page_no=2&page_size=25
7.1.2 参数
参数名类型描述
4.2.1 系统级参数全体
4.2.2 业务级参数全体
cid int 百度知道的分类ID qstatus int 问题状态 0为待解决 1为已解决7.1.3 返回值
, Response XML 示例
, Response XML 标签说明
标签名描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称 7.2
baidu.zhidao.getQuestionSearch 7.2.1 功能
基于检索关键字在百度知道中搜索匹配的问题列表 URL Demo:
;method=baidu.zhidao.getQuestionSear
ch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京+百度大厦&qstatus=0
&page_no=2&page_size=25
7.2.2 参数
参数名类型描述
4.2.1 系统级参数全体
4.2.2 业务级参数全体
string 检索关键字多个检索关键字之间使用+号连接 keywords
qstatus int 问题状态 0为待解决 1为已解决 7.2.3 返回值
, Response XML 示例
, Response XML 标签说明
标签名描述
id 问题ID
url 该问题在百度知道的URL
title 问题标题
content 提问内容
cid 该问题在百度知道所属的分类ID
cname 该问题在百度知道所属的分类名称 7.3
baidu.zhidao.getQuestionInfo 7.3.1 功能
基于百度知道问题ID获取对应问题的数据以及回答 URL Demo:
;method=baidu.zhidao.getQuestionInfo
&call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482 7.3.2 参数
参数名类型描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID
7.3.3 返回值
, Response XML 示例
, Response XML 标签说明
标签名描述
questionInfo 问题内容数据～具体明细参考7.1和7.2
bestAnswers 最佳答案列表
answers 普通答案列表
content 回答内容
cite 回答参考资料
pic_url 回答贴图URL
7.4 baidu.zhidao.getQuestionAnswer 7.4.1 功能
基于百度知道问题ID、回答ID获取对应问题的数据的回答 URL Demo: ;method=baidu.zhidao.getQuestionInfo
&call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482&aid=1232142352
7.4.2 参数
参数名类型描述
4.2.1 系统级参数全体
qid int 百度知道的问题ID aid int 百度知道的回答ID 7.4.3 返回值, Response XML 示例
, Response XML 标签说明
标签名描述
questionInfo 问题内容数据～具体明细参考7.1和7.2
answerInfo 回答内容数据
7.5 baidu.zhidao.question 7.5.1 功能
向百度知道进行提问
URL Demo:
参数全部为POST方式
7.5.2 参数
参数名类型描述
4.2.1 系统级参数全体api_key method call_id format bd_sig(POST) title string POST字段问题标题 content string POST字段问题内容 utype string POST字段用户类型～例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid
uname string POST字段第三方账号系统uname 7.5.3 返回值
, Response XML 示例
, Response XML 标签说明
标签名描述
error_code 错误号～0为成功
error_msg 错误描述
qid 提问成功后返回的qid
7.6 baidu.zhidao.answer 7.6.1 功能
向百度知道的待解决问题进行回答
URL Demo:
参数全部为POST方式
7.6.2 参数
参数名类型描述
4.2.1 系统级参数全体api_key method call_id format bd_sig (POST) qid string POST字段提供回答的问题ID content string POST字段回答内容 cite string POST字段回答参考资料 pic_url string POST字段回答的贴图 utype string POST字段用户类型～例如baidu、renren、wanmei
uid int POST字段第三方账号系统uid uname string POST字段第三方账号系统uname 7.6.3 返回值
, Response XML 示例
, Response XML 标签说明
标签名描述
error_code 错误号～0为成功
error_msg 错误描述
qid 回答成功后返回的问题id
8 第三方提供API接口细则
使用提问API,baidu.zhidao.question,的第三方～其用户使用该API提交提问之后～如果知道平台上有用户对该提问进行了回答～那么是需要一种机制反馈给第三方API调用者～以便及时将回答反馈给提问的用户～解决用户的疑问。本章节描
述提问下产生回答后～第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8
需要第三方提供HTTP的接口～采用POST方法～参数签名加密算法和4.2.3章节描述的算法一致～会使用第三方的密钥进行加密～第三方对之进行有效性校验～需要支持的POST参数如下:
参数名类型描述
method string 值为baidu.zhidao.feedback
qid int 问题ID～知道为int型
aid int 回答ID～知道为int型
utype string 提问用户的用户类型～例如baidu、renren、飞信 uid int 第三方账号系统uid
第三方基于接收到的qid和aid向平台发起请求～调用
baidu.zhidao.getQuestionAnswer API
接口获取对应提问下的回答信息。
第三方合作站点如果不采用消息提醒=》抓取回答内容的方式～可以选择下面这个直接接收回答数据的方法～仍然是HTTP接口～POST方法～参数签名加密算法和4.2.3章节描述的算法一致～会使用第三方的密钥进行加密～第三方对之进行有效性校验～需要支持的POST参数如下:
参数名类型描述
method string 值为baidu.zhidao.feedAnswer
qid int 问题ID～知道为int型
aid int 回答ID～知道为int型 utype string 提问用户的用户类型～例如baidu、renren、wanmei uid int 第三方账号系统uid
content string 回答内容
cite string 回答参考资料
pic_url string 回答的贴图URL
第三方合作接收到平台的回答反馈后～需要按指定数据格式输出数据信息～输出数据格式为
UTF-8编码的XML接口。具体数据格式为:
, Response XML 示例
baidu.zhidao.feedback接口返回:
baidu.zhidao.feedAnswer接口返回:
, Response XML 标签说明
标签名描述
error_code 错误号～0为成功
error_msg 错误描述
上述两种POST HTTP接口～对于使用提问API的第三方～实现一种即可～应用注册申请时指明
具体采用策略即可。
9 附件及参考资料
API接口文档
API接口文档 最后更新日期：2013-05-16 一、添加域名接口 (6) 1、接口调用地址 (6) 2、传入参数 (6) 3、输出数据 (6) 二、删除域名接口 (7) 1、接口调用地址 (7) 2、传入参数 (7) 3、输出数据 (7) 三、添加用户接口 (8) 1、接口调用地址 (8) 2、传入参数 (8) 3、输出数据 (8) 四、获取用户信息接口 (9) 1、接口调用地址 (9) 2、传入参数 (9) 3、输出数据 (9) 五、搜索用户接口 (10) 1、接口调用地址 (10) 2、传入参数 (10) 3、输出数据 (10) 六、修改用户接口 (11) 1、接口调用地址 (11) 2、传入参数 (11) 3、输出数据 (12) 七、删除用户接口 (13) 1、接口调用地址 (13) 2、传入参数 (13) 3、输出数据 (13) 八、获取邮箱别名接口 (14) 1、接口调用地址 (14) 2、传入参数 (14) 3、输出数据 (14) 九、获取部门列表接口 (15) 1、接口调用地址 (15) 2、传入参数 (15) 3、输出数据 (15) 十、添加部门接口 (17) 1、接口调用地址 (17)
3、输出数据 (17) 十一、修改部门接口 (18) 1、接口调用地址 (18) 2、传入参数 (18) 3、输出数据 (18) 十二、删除部门接口 (19) 1、接口调用地址 (19) 2、传入参数 (19) 3、输出数据 (19) 十三、获取部门成员接口 (20) 1、接口调用地址 (20) 2、传入参数 (20) 3、输出数据 (20) 十四、添加部门成员接口 (21) 1、接口调用地址 (21) 2、传入参数 (21) 3、输出数据 (21) 十五、删除部门成员接口 (22) 1、接口调用地址 (22) 2、传入参数 (22) 3、输出数据 (22) 十六、添加别名接口 (23) 1、接口调用地址 (23) 2、传入参数 (23) 3、输出数据 (23) 十七、修改别名接口 (24) 1、接口调用地址 (24) 2、传入参数 (24) 3、输出数据 (24) 十八、删除别名接口 (25) 1、接口调用地址 (25) 2、传入参数 (25) 3、输出数据 (25) 十九、获取POP接收邮件接口 (26) 1、接口调用地址 (26) 2、传入参数 (26) 3、输出数据 (26) 二十、添加POP接收邮件接口 (27) 1、接口调用地址 (27) 2、传入参数 (27) 3、输出数据 (27) 二十一、修改POP接收邮件接口 (28) 1、接口调用地址 (28)
Web Services业务接口规范说明书
XXXX系统 Web Services业务接口规范说明书 拟制 审核 会签 批准 【公司名称】
版本历史
目录 1.范围 (1) 2.术语、定义和缩略语 (1) 2.1 术语、定义 (1) 2.2 缩略语 (1) 3.接口设计 (1) 3.1 接口公共参数 (1) 3.1.1请求参数 (1) 3.1.2返回参数 (2) 3.2 业务功能接口 (3) 3.2.1业务模块1 (3) 4.MD5加密 (6) 5.参考文献 (6)
1.范围 本规范文档主要适用于XXXX系统和其它业务系统信息数据的接入。 2.术语、定义和缩略语 2.1术语、定义 2.2缩略语 3.接口设计 3.1接口公共参数 接口服务器通过：http://IP:port/EIP/WebService/ 连接服务器，同时对外提供业务功能接口，接收的参数和返回的参数都用一定的xml格式进行封装。 3.1.1请求参数 1.请求类型为String类型
3.请求参数体param定义 参数体param中的具体请求参数，根据不同的业务而不同，详见各业务接口。 3.1.2返回参数 1.返回类型为String类型
系统设计文档模板
系统设计说明书（架构、概要、详细）目录结构 虽然这些文档一般来说公司都是有模板的，但我写这些文档以来基本上是每写一次就把目录结构 给改一次，应该说这是因为自己对这些文档的理解开始加深，慢慢的越来越明白这些文档的作用 和其中需要阐述的东西，觉得这三份文档主要阐述了一个系统的设计和实现过程，从系统分解为层次、层次内的模块以及相互的接口、模块分解为对象以及对象的接口、实现这些对象接口的方法。这次又整了一份，A/ ，欢迎大家指正。 XXX架构设计说明书 （架构设计重点在于将系统分层并产生层次内的模块、阐明模块之间的关系）一?概述 描述本文的参考依据、资料以及大概内容。 二.目的 描述本文编写的目的。 三.架构设计 阐明进行架构设计的总体原则，如对问题域的分析方法。 3.1. 架构分析 对场景以及问题域进行分析，构成系统的架构级设计，阐明对于系统的分层思想。 3.2. 设计思想 阐明进行架构设计的思想，可参考一些架构设计的模式，需结合当前系统的 实际情况而定。 3.3. 架构体系 根据架构分析和设计思想产生系统的架构图，并对架构图进行描述，说明分层的原因、层次的职责，并根据架构图绘制系统的物理部署图，描述系统的部署体系。3.4. 模块划分 根据架构图进行模块的划分并阐明模块划分的理由，绘制模块物理图以及模
块依赖图。 341. 模块描述 根据模块物理图描述各模块的职责，并声明其对其他模块的接口要求。。 3.4.2. 模块接口设计 对模块接口进行设计，并提供一定的伪代码。 XXX概要设计说明书 （概要设计重点在于将模块分解为对象并阐明对象之间的关系） 一.概述 描述本文的参考依据、资料以及大概内容。 二.目的 描述本文的编写目的。 三.模块概要设计 引用架构设计说明书中的模块图，并阐述对于模块进行设计的大致思路。 3.1. 设计思想 阐明概要设计的思想，概要设计的思想通常是涉及设计模式的。 3.2. 模块A 3.2.1. 概要设计 根据该模块的职责对模块进行概要设计（分解模块为对象、描述对象的职责以及声明对象之间的接口），绘制模块的对象图、对象间的依赖图以及模块主要功能的序列图，分别加以描述并相应的描述模块异常的处理方法。 3.2.2. 模块接口实现 阐明对于架构设计中定义的模块接口的实现的设计。 XXX详细设计说明书 （详细设计重点在于对模块进行实现，将模块的对象分解为属性和方法，并阐述 如何实现）
接口设计规范
目录 1接口类型 (2) 1.1人机接口 (2) 1.2软件-硬件接口 (2) 1.3软件接口 (2) 1.4通信接口 (2) 2接口设计规范 (2) 2.1基本内容 (2) 2.2规格说明 (3) 2.2.1人机接口 (3) 2.2.2软件-硬件接口 (3) 2.2.3软件接口 (3) 2.2.4通信接口 (3) 3接口设计文档提纲 (3)
1接口类型 1.1人机接口 人机接口是指计算机系统为完成人与机器之间互相传送信息而提供的功能的接口，包括硬件及程序。 1.2软件-硬件接口 软件-硬件接口是指软件系统中软件与硬件之间的接口。例如软件与接口设备之间的接口。 1.3软件接口 软件接口是软件系统中程序之间的接口。包括软件系统与其他系统或子系统之间的接口、程序模块之间的接口、程序单元之间的接口等。 1.4通信接口 通信接口是指处理机和标准通信子系统之间的接口。包括为实现数据通信用来完成接口功能的部件、装置及有关软件。 2接口设计规范 2.1基本内容 1、接口的名称标识 2、接口在该软件系统中的地位和作用 3、接口在该软件系统中与其他程序模块和接口之间的关系 4、接口的功能定义 5、接口的规格和技术要求，包括它们各自适用的标准、协议或约定 6、各个接口的数据特性 7、各个接口的资源要求，包括硬件支持、存储资源分配等 8、接口程序的数据处理要求
9、接口的特殊设计要求 10、接口对程序编制的要求 2.2规格说明 2.2.1人机接口 准确地说明人机接口的设计条件、设计特征、编程要求等技术内容。包括人机交互环境、人机接口部件、信息传输方式及传输特性、信息格式、数据处理、存储资源分配和程序编制要求等。 2.2.2软件-硬件接口 逐个描述每一个软件-硬件间接口的设计特性。包括接口硬件说明、接口功能说明、接口信息说明、接口处理方法、接口控制方式、接口时间特性、存储资源分配和程序编制要求等。 2.2.3软件接口 逐个说明本软件系统与其他软件系统间接口的设计特征。包括接口功能说明、接口约定、数据特性、数据处理方法、接口程序运行控制、接口时间特性、存储资源分配和程序编制要求等。 2.2.4通信接口 逐个描述各个通信接口的设计特性。包括硬件描述、接口功能说明、通信协议、报文处理、存储资源分配、程序接口设计和程序编制要求等。 3接口设计文档提纲 1概述........................................................................................................................................................... 错误！未定义书签。 1.1编写目的......................................................................................................................................... 错误！未定义书签。 1.2参考资料......................................................................................................................................... 错误！未定义书签。 1.3术语和缩写词................................................................................................................................ 错误！未定义书签。2软件系统综述......................................................................................................................................... 错误！未定义书签。3接口设计.................................................................................................................................................. 错误！未定义书签。 3.1接口框图......................................................................................................................................... 错误！未定义书签。 3.2接口一览表.................................................................................................................................... 错误！未定义书签。 3.3人机接口......................................................................................................................................... 错误！未定义书签。 3.4软件-硬件接口 .............................................................................................................................. 错误！未定义书签。
开发接口文档-API文档模板
XXX项目接口文档版本控制信息 获取所有字段 获取所有字段 请求地址：/session/field/findAll 请求参数 响应
请求例子：响应例子：{"code":"10000","exception":null,"isSuccess":true,"message":"成功，系统处理正常！ ","page":0,"pageSize":0,"returnObject":null,"returnValue":{"types":null,"villages":null,"companys":[{"iconColour":"","iconSize":0,"ico nStyle":"","id":4,"name":"XX"},{"iconColour":"","iconSize":0,"iconStyle":"","id":5,"name":"XX"},{"iconColour":"","iconSize":0,"iconSty le":"","id":7,"name":"XX"}]},"totals":0} 文件上传 文件上传（ajax） 请求地址：/session/file/upload 请求参数 响应 请求例子：var formData = new FormData(); ("file", [0]); $.ajax({ url : routePath + "/session/file/upload", type : 'POST', data : formData,
processData : false, contentType : false, success : function(result) { result = (result); if == "10000"){ ('上传成功！'); $("#editHeadPortrait").val } } }); 响应例子：returnValue里包含了 fileName和filePath 字段管理-所属类型 新增所属类型 请求地址：/session/fieldType/save 请求参数 响应 请求例子：响应例子：{"code":"10000","exception":null,"isSuccess":true,"message":"成功，系统处理正常！","page":0,"pageSize":0,"returnListSize":0,"returnObject":null,"returnValue":null,"totals":0}
接口文档规范
XXX接口说明书(版本：V1.0)
修订记录
1简介 1.1文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2接口规范 (1) 遵循RESTful API设计风格 (2) 数据格式采用json格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data:{}, // 数据类型不一定为object类型 errorCode:10001, msg:'' } (4) 枚举型参数应列举参数所有值及说明 例如： gender：性别（男：1，女：2） userInfo:{ name:'张三', age:23, gender:1 }
(5) 具有嵌套关系的参数应指明嵌套关系及子级数据结构例如： billList: 账单列表(父级) billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] (6) 返回参数数据类型保持一致性 例如： billList: 账单列表（有数据） billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' } ] billList: 账单列表（无数据） billList:[] 返回的参数数据类型都为：array (7) 下拉及选择型数据以键值对的形式返回 例如： orderOperate：订单操作 orderOperate:[
接口控制文件(模版)
文件修订页
目录 1 范围 (1) 1.1系统概述 (1) 1.2文档概述.................................................................................................错误!未定义书签。 1.3术语与缩略语 (1) 2 引用文档 (1) 3 接口设计 (1) 3.1外部接口 (1) 3.2用户接口 (2) 3.3内部接口 (2)
1 范围 1.1 系统概述 描述软件系统的运行环境、主要用途，描述软件系统的总体功能、构成、子系统构成。使得读者对系统有一个总体的概要的了解。 [读者看完系统概述知道了这个软件是做什么用的、主要的功能是什么，用在什么样的场合。这样读者就可以对系统有一个整体的了解]。 1.2 术语与缩略语 本文档使用的术语与缩略语： XXXX ：XXXXXXXXXXXX； ……； 2 引用文档 [1]《XXXXXXX》，XXXXXXXXXX，YYYY年MM月。 [2]《XXXXXXX》，XXXXXXXXXX，YYYY年MM月。 ……。 3 接口设计 3.1外部接口 说明该系统同外界的所有接口安排，包软件接口与硬件接口。 <说明本系统同外界的所有接口的安排包括软件与硬件之间的接口、本系统与各支持软件之间的接口关系。> 例如：通讯接口、直接硬件接口、支撑软件接口以及与其它软件模块间的接口设计。 1）外部网络通讯接口设计 外部通讯网络接口设计是指与本系统范围外的网络接口，如上层管理网等的接口和协议、信息流向、信息、长度和通讯周期等。 2）外部串行口通讯接口设计 外部串行口通讯接口设计是指与本系统范围外的其它系统采用串行口通讯时的接口关系，包括通讯协议(握手方式、波特率、校验方式等)、信息流向、信息长度和通讯周期等。还应说明当通讯过于频繁或超时时的措施。
API 接口 设计文档 模板
Dream调试工具DLL接口文档 文件状态：[√] 草稿[ ] 正式发布[ ] 正在修改当前版本： 1.0 作者：ChunFeng Li 文件密级：[ ]普通[√]秘密[ ]绝密 文档版本 版本/状态作者参与者日期说明 1.0 ChunFeng Li ChunFeng Li 2016-04-13 设备只能发现串口连接的设备，指 令只能下发单条修改 一、DLL初始化 1.描述 调用所有接口之前需要先调用初始化接口。 2.接口名（dll导出名） Dream_Init() 3.请求参数说明 参数字段必选类型限制说明 _net_point True int<65535 Udp广播端口号 _com_rate True int 38400 连接串口的默认波特率 _call_back True Void* ... 异步消息回调（详细见第五条：回调函数） 4.返回参数说明 a.返回类型Int :0成功-1重复初始化 二、获取最新设备列表 1.描述 调用该接口获取所有当前在线列表。 2.接口名（dll导出名） Dream_GetDeviceList() 3.请求参数说明
char_buf True char* 1024 存放返回数据的内存指针，空间大小有调 用方分配 buf_len True int 1024 分配的空间大小 4.返回参数说明 a.返回类型Int : 返回数据长度。 b.返回数据结构:”1000,COM3\r\n1001,COM5\r\n1002,192.168.0.118\r\n”。 [ID,Name\r\n]为一个设备，以后有跟多设备详细信息，往后接。 三、发送指令消息 1.描述 下发数据和读取数据指令都通过该接口实现。(阻塞方式调用函数) 2.接口名（dll导出名） Dream_SendAction() 3.请求参数说明 参数字段必选类型限制说明 device_id True int>1000 发送消息的设备ID例如1000 _ChannelCode True int 0-0xFF 通道编码：例如0x10 _FunctionCode True int 0-0xFF 功能编码，不同的编码对应不同的功能_FunctionNumber True int 0-0xFF 功能编号，标记当前编码对应不同的功能data_msg True char* 发送指令的data，没有数据为NULL，如 果是单个数据：12.1，如果是整组数据： 12.1,1,0,...... 按顺序逗号隔开的连续字符 time_out True int 20*N 接口调用超时时间，单位毫秒 out_buf True char* 存放返回数据的内存指针，空间大小有调 用方分配 buf_max_len True int 分配的空间大小 4.返回参数说明 a.返回类型Int : 返回数据长度。如果为0,表示超时或网络异常 b.返回的数据结构：如果是下发数据，返回的是成功和失 败；”ACK”,”NAK”,”NO_CMD”,”ERROR”,”TimeOut”,如果是读取数据，返回的是数据， 例如12.1，或数据组12.1,12.2,1,1.2..... 四、DLL初始化 1.描述 下发数据和读取数据指令都通过该接口实现。(非阻塞方式调用函数) 2.接口名（dll导出名） Dream_SendAction() 3.请求参数说明
软件需求说明书编写规范
{产品名称} 软件需求规格说明书 编写人： 编写日期：年月日
目录 1.产品描述 (3) 1.1.编写目的 (3) 1.2.产品名称 (3) 1.3.名词定义（可选） (3) 2.产品需求概述 (3) 2.1.功能简介 (3) 2.2.运行环境 (3) 2.3.条件与限制（可选） (3) 3.功能需求 (3) 3.1.功能划分（可选） (3) 3.2.功能1 (4) 3.3.功能N (4) 3.4.不支持的功能 (4) 4.数据描述 (4) 5.性能需求（可选） (4) 6.运行需求（可选） (4) 6.1.用户界面 (4) 6.2.硬件接口 (4) 6.3.软件接口 (5) 6.4.通信接口 (5) 7.其它需求（可选） (5) 8.特殊需求（可选） (5) 9.不确定的问题（可选） (5) 10.编写人员及编写日期 (5) 11.附录 (5) 11.1.引用文件 (5) 11.2.参考资料 (5)
1.产品描述 1.1.编写目的 【说明编写本软件需求规格说明书的目的，指出预期的读者。】 1.2.产品名称 【本项目的名称，包括项目的全名、简称、代号、版本号。】 1.3.名词定义（可选） 【对重要的或是具有特殊意义的名词（包括词头和缩写）进行定义，以便读者可以正确地解释软件需求说明。】 2.产品需求概述 2.1.功能简介 【对产品的基本功能做一个简介，包括： 1.本产品的开发意图、应用目标及作用范围。 2．概略介绍了产品所具有的主要功能。可以用列表的方法给出，也可以用图形表示主要的需求分组以及它们之间的联系，例如数据流程图的顶层图或类图等。 3．说明本产品与其他相关产品的关系，是独立产品还是一个较大产品的组成部分。 可以用表示外部接口和数据流的系统高层次图，或者方框图说明。】 2.2.运行环境 1.硬件环境： 【详细列出本软件运行时所必须的最低硬件配置、推荐硬件配置(如主机、显示器、外部设备等)以及其它特殊设备。】 2.软件环境： 【如操作系统、网络软件、数据库系统以及其它特殊软件要求。】 2.3.条件与限制（可选） 【说明本软件在实现时所必须满足的条件和所受的限制，并给出相应的原因。 必须满足的条件包括输入数据的范围以及格式。 所受的限制包括软件环境、硬件环境等方面的内容。例如：必须使用或者避免的特定技术、工具、编程语言和数据库；企业策略、政府法规或工业标准；硬件限制，例如定时需求或存储器限制；经费限制、开发期限；项目对外部因素存在的依赖。例如其它项目开发的组件。等等】 3.功能需求 【功能需求描述系统特性，即产品所提供的主要服务。可以通过使用实例、运行模式、用户类、对象类或功能等级等不同方法来描述，还可以把它们组合起来使用。 功能需求的表述形式可以参见《需求分析和管理指南》第8.2节。】 3.1.功能划分（可选） 【此部分从用户的角度描述将软件划分成不同的部分，并给出总体功能结构。对于复杂
软件详细设计文档模板(最全面)
研发生产中心文档编号版本A1 密级商密A 项目名称Xx系统 项目来源 Xxx系统 详细设计说明书 (内部资料请勿外传) 编写：日期：检查：日期：审核：日期：批准：日期： XX公司 版权所有不得复制 文档变更记录
序号变更（+/-）说明作者版本号日期批准1 2
目录 1. 引言 (5) 1.1 编写目的和范围 (5) 1.2 术语表 (5) 1.3 参考资料 (5) 1.4 使用的文字处理和绘图工具 (5) 2. 全局数据结构说明 (7) 2.1 常量 (7) 2.2 变量 (8) 2.3 数据结构 (8) 3. 模块设计 (9) 3.1 用例图 (9) 3.2 功能设计说明 (10) 3.2.1 模块1 (10) 3.2.2 模块2 (11) 4. 接口设计 (12) 4.1 内部接口 (12) 4.2 外部接口 (12) 4.2.1 接口说明 (12) 4.2.2 调用方式 (12) 5. 数据库设计 (12) 6. 系统安全保密设计 (12) 6.1 说明 (12) 6.2 设计 (12) 6.2.1 数据传输部分 (12) 6.2.2 IP过滤分部 (13) 6.2.3 身份验证部分 (13) 7. 系统性能设计 (13) 8. 系统出错处理 (13)
1.引言 1.1背景 此文档的背景 1.2编写目的和范围 说明写这份详细设计说明书的目的。 本详细设计说明书编写的目的是说明程序模块的设计考虑，包括程序描述、输入/输出、算法和流程逻辑等，为软件编程和系统维护提供基础。本说明书的预期读者为系统设计人员、软件开发人员、软件测试人员和项目评审人员。 1.3术语表 定义系统或产品中涉及的重要术语，为读者在阅读文档时提供必要的参考信息。 序号术语或缩略语说明性定义 1 PM Project Manager,项目经理 2 1.4参考资料 列出有关资料的名称、作者、文件编号或版本等。参考资料包括： a．需求说明书、架构设计说明书等； b．本项目的其他已发表的文件； c．引用文件、资料、软件开发标准等。 资料名称作者文件编号、版本资料存放地点 1.5使用的文字处理和绘图工具 文字处理软件：[编写设计文档使用的文字处理软件，如RedOffice ] 绘图工具：[使用的UML工具，如Rose、Jude、Visio]
完整的接口解决方案说明书
文档编号：T-JKJS 文档版本：0.01 项目编号：XX-DX- PECS 《XX电信工程外部协作系统》 Project Exterior Cooperation System 施工单位接口技术解决方案 编写人：南疯日期：2006-10-30 审核人：日期： 批准人：日期： XXXXXX信息科技股份有限公司 地址：XXXXXXX 邮编：XXXXXX 电话：XXXXXXXX传真：XXXXXX 网站：XXXXXXXXX 修改记录（Revision Chart） 版本号批准人修改人修改0.01南疯2006-10-30 0.02详细修改记录： 序号
1引言 1.1编写目的 1.2覆盖范围 1.3预期读者与阅读建议 1.4文档约定 1.5术语与缩略语 1.6参考文献 2概述 3接口方式 4接口安全 4.1接口认证 4.2数据安全 5事务处理 6性能考虑 7容错处理 8数据格式 8.1约定 8.2施工系统向外协系统发送请求 8.2.1请求查询一个业务数据 8.2.2新增一条记录，得到记录的键值 8.2.3修改一条记录 8.2.4删除一条记录 8.2.5文档上传 8.2.6一条记录中一个文档字段上传多个文件 8.2.7补充上传文档 8.2.8在记录中删除一个文档 8.2.9获得文档的基本信息 8.2.10获得文档的所有兄弟信息 8.2.11获得文档的所有父亲信息 8.2.12下载一个文档 8.2.13获得字典 8.3外协系统向施工系统发送请求 8.3.1发送变更后的数据 8.3.2发送变更后的字典 8.3.3文档发送请求 9信息数据项 9.1数据表 9.2字段信息 9.3字典类型
(完整word)软件项目文档全套模板-需求说明,推荐文档
＜项目名称＞ 软件需求说明书 作者： 完成日期： 签收人： 签收日期： 修改情况记录：
目录 1 引言 (1) 1.1 编写目的 (1) 1.2 范围 (1) 1.3 定义 (1) 1.4 参考资料 (1) 2 项目概述 (2) 2.1 产品描述 (2) 2.2 产品功能 (2) 2.3 用户特点 (2) 2.4 一般约束 (2) 2.5 假设和依据 (3) 3 具体需求 (3) 3.1 功能需求 (3) 3.1.1 功能需求1 (3) 3.1.2 功能需求2 (4) 3.1.n 功能需求n (5) 3.2 外部接口需求 (5) 3.2.1 用户接口 (5) 3.2.2 硬件接口 (5) 3.2.3 软件接口 (5) 3.2.4 通信接口 (6) 3.3 性能需求 (6) 3.4 设计约束 (6) 3.4.1 其他标准的约束 (6) 3.4.2 硬件的限制 (7) 3.5 属性 (7) 3.5.1 可用性 (7) 3.5.2 安全性 (7) 3.5.3 可维护性 (7) 3.5.4 可转移＼转换性 (8) 3.5.5 警告 (8) 3.6 其他需求 (8) 3.6.1 数据库 (8) 3.6.2 操作 (8) 3.6.3 场合适应性需求 (9) 4 附录 (9)
1 引言 1.1 编写目的 说明编写这份软件需求说明书的目的，指出预期的读者范围。 1.2 范围 说明： a．待开发的软件系统的名称； b．说明软件将干什么，如果需要的话，还要说明软件产品不干什么； c．描述所说明的软件的应用。应当： 1）尽可能精确地描述所有相关的利益、目的、以及最终目标。 2）如果有一个较高层次的说明存在，则应该使其和高层次说明中的类似的陈述相一致（例如，系统的需求规格说明）。 1.3 定义 列出本文件中用到的专门术语的定义和缩写词的原词组。 1.4 参考资料 列出要用到的参考资料，如： a．本项目的经核准的计划任务书或合同、上级机关的批文； b．属于本项目的其他已发表的文件； c．本文件中各处引用的文件、资料，包括所要用到的软件开发标准。 列出这些文件的标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料的来源。
接口设计规范V1.0 - 参考
服务端与手机平台 接口协议 BespRout 2014年11月
文档修改/审批记录
目录 1.概述 (4) 2.涉及接口 (4) 3.接口总体要求 (4) 3.1.系统间接口的原则 (4) 3.2.处理流程 (4) 3.3.接口实现方式 (5) 4.XXX服务端接口 (5) 4.1.XX模块-根据XX下载相关的配置文件 (5) 4.2.XX模块-生成指定XX的文件配置 (6) 4.3.APP启动-初使化参数 (7) 5.附件 (8) 5.1.备注说明 (8)
1. 概述 本文档提供接口给手机端使用，为手机端提供业务平台数据 2. 涉及接口 本文档涉及的外围系统接口包括：无 3. 接口总体要求 3.1.系统间接口的原则 接口设计遵循如下原则： ?安全可靠性原则：系统应提供良好的安全性和可靠性策略，支持多种安全而 可靠的技术手段，制定严格的安全可靠的管理措施； ?开放性原则：提供开放式标准接口，提供与其它系统的互联互通； ?灵活性原则：提供灵活的接口设计，便于接口的变动。 ?可扩展性原则：支持新业务的扩展以及接口容量与接口性能的提高； ?可管理性原则：提供良好的管理机制，保证在运行过程中提供给管理员方便 的管理方式以处理各种情况； ?统一性原则：应当保证系统的接口方式、接口形式、使用的协议等标准、统 一。 3.2.处理流程 接口处理流程
3.3. 接口实现方式 手机APP 应用 与服务端采用基于HTTP 的REST 协议完成，数据传输默认为JSON 4. XXX 服务端接口 测试地址前缀: http://192.168.3.208:8088/xxx/xxx 4.1. XX 模块-根据XX 下载相关的配置文件
京东API接口整理
1、类目API 获取商家类目信息 获取类目属性 通过类目属性ID获取属性值列表 设置商家级别的类目销售属性值 添加商家商品销售属性 更新商家商品销售属性 获取类目属性列表 获取类目属性值 获取单个类目信息 查找子类目列表 查询商家已授权的品牌 数据结构 item_cat categoryAttr类目属性对象 attrFeature类目属性特殊属性 categoryAttrGroup属性分组 attrGroupFeature属性分组特殊属性 categoryAttrValue类目属性值对象 attrValueFeature类目属性特殊属性 feature特殊属性 wareaddvender_sellsku添加商家商品销售属性
wareupdatevender_sellsku更新商家商品销售属性 brandList商家品牌List集合 2、店铺API 京东店铺API，包含提供商家、商家店铺基本信息及店内分类操作查询等功能。 添加卖家自定义店内分类 更新商家自定义店内分类 删除商家自定义店内分类 获取前台展示的商家自定义店内分类 查询商家基本信息 店铺信息查询 查询退货地址列表 查询发货地址列表 3、商品API 提供网站商品信息更新、查询API,该组下所有接口均不支持自营店铺业务 1. 新增商品 修改商品 商品上架 商品下架 删除商品信息 根据商品ID查询单个商品的详细信息 批量获取商品信息 检索商品信息
获取商品上架的商品信息 获取商品下架的商品信息 根据商品Id，销售属性值Id查询图片根据商品Id，销售属性值Id增加图片根据商品Id，销售属性值Id删除图片根据商品Id，销售属性值Id设置图片根据商品Id，检索商品图片 设置商品限购区域 查询商品限购区域 添加商品关联版式 修改商品关联版式 删除商品关联版式 查询关联版式id以及名称 查询关联版式详情 设置关联版式到商品 增加SKU信息 修改SKU信息 修改SKU库存信息 修改SKU价格信息 删除SKU 信息 根据外部ID获取商品SKU 根据商品ID列表获取商品SKU信息 获取单个SKU信息 回复商品评价 查询商品评价信息列表
API接口设计说明书
XXAPI 接口设计说明书 公司 2016年11月25日 文档管理信息表 主题XX api接口设计说明书 版本V0.1 内容 关键字 参考文档 创建时间 创建人 最新发布日期 文档变更记录表 修改人修改时间修改内容 创建
目录 文档变更记录表 .................................................................................................................................................................................. 目录 .................................................................................................................................................................................................... 引言 ...................................................................................................................................................................................................... 编写目的 背景 定义 参考资料 综述 ...................................................................................................................................................................................................... 统一的输入输出参数 必须登录才能访问的接口 错误返回码列表 用户接口 .............................................................................................................................................................................................. 用户注册（user/signup） 用户登录（user/signin） 优惠券接口 .......................................................................................................................................................................................... 我的优惠券（coupon/mycoupon）
api接口文档
API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。API除了有应用“应用程序接口”的意思外，还特指API的说明文档，也称为帮助文档。 API：应用程序接口（API：Application Program Interface） 应用程序接口（是一组定义、程序及协议的集合，通过API 接口实现计算机软件之间的相互通信。API 的一个主要功能是提供通用功能集。程序员通过调用API 函数对应用程序进行开发，可以减轻编程任务。API 同时也是一种中间件，为各种不同平台提供数据共享。 根据单个或分布式平台上不同软件应用程序间的数据共享性能，可以将API 分为四种类型： 远程过程调用（RPC）：通过作用在共享数据缓存器上的过程（或任务）实现程序间的通信。 标准查询语言（SQL）：是标准的访问数据的查询语言，通过数据库实现应用程序间的数据共享。 文件传输：文件传输通过发送格式化文件实现应用程序间数据共享。
信息交付：指松耦合或紧耦合应用程序间的小型格式化信息，通过程序间的直接通信实现数据共享。 当前应用于API 的标准包括ANSI 标准SQL API。另外还有一些应用于其它类型的标准尚在制定之中。API 可以应用于所有计算机平台和操作系统。这些API 以不同的格式连接数据（如共享数据缓存器、数据库结构、文件框架）。每种数据格式要求以不同的数据命令和参数实现正确的数据通信，但同时也会产生不同类型的错误。因此，除了具备执行数据共享任务所需的知识以外，这些类型的API 还必须解决很多网络参数问题和可能的差错条件，即每个应用程序都必须清楚自身是否有强大的性能支持程序间通信。相反由于这种API 只处理一种信息格式，所以该情形下的信息交付API 只提供较小的命令、网络参数以及差错条件子集。正因为如此，交付API 方式大大降低了系统复杂性，所以当应用程序需要通过多个平台实现数据共享时，采用信息交付API 类型是比较理想的选择。 API 与图形用户接口（GUI）或命令接口有着鲜明的差别：API 接口属于一种操作系统或程序接口，而后两者都属于直接用户接口。 有时公司会将API 作为其公共开放系统。也就是说，公司制定自己的系统接口标准，当需要执行系统整合、自定义和程序应用等操作时，公司所有成员都可以通过该接口标准调用源代码，该接口标准被称之为开放式API。
接口文档规范
XXX接口说明书 (版本： 文档编号保密等级 作者最后修改日期 审核人最后审批日期 批准人最后批准日期
修订记录 日期版本修订说明修订人
1简介 1.1文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2接口规范 (1) 遵循RESTful API设计风格 (2) 数据格式采用json格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data:{}, .] 订单列表 orderList orderId string 否订单id orderName string 否订单名称
isStudent boolean 是false false 是否学生（是：true，否： false） 返回参数： 参数名类型示例值默认值描述 data array […]返回的数据 data id string 用户id gender number 1 1 用户性别（男：1，女：2）invoiceTitle string 抬头 address string 地址 billList array [...] 订单列表数据 billList id string 订单id billName string 订单名称 billStauts number 1 1 订单状态（待开票：1，回款： 2，核销：3） address string 客户地址 userInfo object {} 用户信息 userInfo name name 用户姓名 age number 用户年龄 gender string 1 1 用户性别（男：1，女：2）errorCode number 状态信息 msg string 信息提示 返回示例值: { data:[ { id:'1', gender:2, invoiceTitle:'帝国快运', address:'陕西省西安市雁塔区科技路24号', billList:[ { id:'001', billName:'测试数据', billStauts:1, address:'雁塔区' }, { id:'002', billName:'测试数据02',