API 接口设计规范 _API

文章插图

协议httphttps（使用HTTPS协议，以确保交互数据的传输安全）域名专门的api应用使用独立域名 https://api.example.com简单的可使用api前缀区分 https://www.example.com/api版本控制接口版本的控制，可以在程序发布时，不同版本的业务逻辑在一定程度上避免受到影响。
https://api.example.com/v{n}

应该将API的版本号放入URL 。
采用多版本并存，增量发布的方式。
n代表版本号，分为整型和浮点型
整型：大功能版本，如v1、v2、v3 ...
浮点型：补充功能版本，如v1.1、v1.2、v2.1、v2.2 ...

URL规则

在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。【所用的名词往往与数据库的表格名对应】
数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

例子https://api.example.com/v1/productshttps://api.example.com/v1/usershttps://api.example.com/v1/employees请求方式

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）：从服务器删除资源。

例子：GET /v1/products 获取所有商品 GET /v1/products/ID 获取某个指定商品的信息 POST /v1/products 新建一个商品 PUT /v1/products/ID 更新某个指定商品的信息 DELETE /v1/products/ID 删除某个商品 GET /v1/products/ID/purchases 列出某个指定商品的所有投资者 GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息方法命名也要具有一定规范

新增以“add”为前缀。例如add{XXX}
删除以“delete”为前缀。例如delete{XXX}
修改以“updata”为前缀。例如updata{XXX}
获取以“get”为前缀。例如get{XXX}
获取以“get”为前缀、“List”为后缀。例如get{XXX}List
保存以“save”为前缀。例如save{XXX}
发送以“send”为前缀。例如send{XXX}
上传以“upload”为前缀。例如upload{XXX}

请求参数

cookie
request header：可以存放requestId，token,加密字段等
请求body数据：针对入参数据，后端必须做数据验证
地址栏参数

响应格式response：
----------------------------------------
{ status: 200, // 详见【status】 data: { code: 1, // 详见【code】 data: {} || [], // 数据 message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】 sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行 ... // 其它参数，如 total【总记录数】等 }, msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】 sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行}status
200: OK 400: Bad Request 500：Internal Server Error 401：Unauthorized 403：Forbidden 404：Not Foundcode
1: 获取数据成功 | 操作成功0：获取数据失败 | 操作失败前后端约定后端