restful 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 Found

code

 1: 获取数据成功 | 操作成功  0：获取数据失败 | 操作失败

前后端约定

后端

• 后端需要保证JSON格式的合法性，前端不对格式的合法性做判断
• 金额格式：所有金额以元为单位，显示性的后台返回的是格式化之后的，例如：6,800
• 时间格式: 尽量以一致格式的字符串传递 2019-01-01 12:12:12
• 数据接口中定义的key集合是后端返回的子集，即key不缺失(参考数据格式，允许传递更多数据)
• key使用驼峰命名，首字母小写
• 空对象请使用[]
• 空列表请使用[]
• 空字符串请使用''
• 默认数字请使用0
• 尽量避免使用null undefined
• 响应头Content-Type为"application/json; charset=UTF-8"
• 接口应该携带requestId唯一标示用来追踪问题
• 敏感度高的数据，客户端和服务器通过约定的算法，对传递的参数值进行签名匹配，防止参数在请求过程中被抓取篡改。
• 包含用户隐私的字段数据，需要加*号。如：手机号，身份证，用户邮箱，支付账号，邮寄地址等。

 "phone":"150*****000