json接⼝⽂档模板_API设计指南-「⼲货」⼀个接⼝⽂档模板
的最佳实践
1. 基础说明
1.1 背景
[说明⽂档⽤途]
编写本⽂的⽬的是为了将系统功能进⾏模块化、服务化，将⽤户的操作以服务的⽅式提供。系统与系统之间遵循服务规范，将系统与系统之间的交互转为定制化服务交互，以实现系统与系统之间的集成。
1.2 基本约束
1.2.1 基本设计原则
请参考上⼀篇⽂章《API设计指南-RestAPI设计最佳实践》。
1.2.2 字符集
所有接⼝字符集采⽤UTF-8。
1.2.3 返回类型约束
所有接⼝返回必须是严格定义的JSON类型。
1.2.4 接⼝版本约束
不允许发布⽆版本号的接⼝。
接⼝版本⾸先解决的是⼀组接⼝的版本问题。
1.3 请求公共约束
请求的基本模板：
curl -X[HTTP METHOD] -H "Content-Type: application/json" -H "[token-info]:""api-[env-name].[groupname].domain.io/[client-group]/[service-group]/[
1.4 URL整体规划
1.4.1 域名规范
api-[env-name].[groupname].domain.io/[client-group]/[service-group]/[version]/[endpoint]
1.4.2 域名规则
开发环境：api-dev.payment.domain.io/
测试环境：api-test.payment.domain.io/
预演环境：api-staging.payment.domain.io/
线上测试环境：api-onlinetest.payment.domain.io/
⽣产环境：api.payment.domain.io/
其中线上测试环境是上线过程中备⽤，⽐如线上⼀共3台⽣产环境服务器，将其中⼀台从⽣产环境切掉，更新程序并且将域名指向它，测试完之后再将⽣产环境流量切换过来。
1.5 基本数据类型约定
此约定是系统整体容错的⼀部分，但是⽆论接⼝使⽤者还是⽣产者，都不应该因为此容错⽽减少⾃⼰模块本来需要的容错⼯作。
1.6 公共输⼊参数规范
1.7 公共返回对象约定
{  "responseCode": [responseCode],  "responseInfo": {    "userMessage": [userMessage],    "internalMessage": [internalMessage],    "guideline": [guideline 1.8 公共错误编码及说明
1.9 公共数据字典
2. 订单服务
2.1 查询订单列表
2.1.1 接⼝规范
百度api接口
2.1.2 输⼊参数⽰范
curl -XGET -H "Content-Type: application/json" -H "Access-Token:abcd1234" "api-dev.haitao.domain.io/mobile/data-platform/v1/orders/base-orders 2.1.3 返回参数⽰范
{  "responseCode": [responseCode],  "responseInfo": {    "userMessage": [userMessage],    "internalMessage": [internalMessage],    "guideline": [guideline

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。