应用接口规范

RESTful模式

一、API版本规范

将API版本号放入URL，例如：https://api.example.com/v{n}/

建议：基于API采用多版本并存，增量发布的方式，其中v{n} n代表版本号,分为整形和浮点型：

1. 整形：大功能版本发布形式；具有当前版本状态下的所有API接口，例如：v1，v2 
2. 浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api，例如：v1.1，v2.2

二、Endpoint（路径）规范

Rest接口参照Restful标准规范

1. 路径中只能有名词，不要有动词，例如：
   正确：https://api.example.com/v1/products，https://api.example.com/v1/contracts
   不能有：https://api.example.com/v1/createProduct，https://api.example.com/v1/addContract，https://api.example.com/v1/deleteContract 等
2. 名词参照对应的表名使用复数形式，即表示记录的Collection集合，不要使用单数，例如：
   正确：https://api.example.com/v1/products，https://api.example.com/v1/contracts
   不能有：https://api.example.com/v1/product，https://api.example.com/v1/contract
3. 单个资源使用/{name}/{resource}的方式，例如：
   https://api.example.com/v1/products/1，https://api.example.com/v1/contracts/3
4. 关联资源情况，例如：
   某产品下的所有订单：https://api.example.com/v1/products/1/orders
   某产品下的某个订单：https://api.example.com/v1/products/1/orders/3

三、HTTP Methods

对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个（括号里是对应的SQL命令）：

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

例如：

GET https://api.example.com/v1/products：获取所有产品列表

POST https://api.example.com/v1/products：新建一个产品

GET https://api.example.com/v1/products/ID：获取某个指定产品的信息

PUT https://api.example.com/v1/products/ID：更新某个指定产品的信息（提供该产品的全部字段信息）

PATCH https://api.example.com/v1/products/ID：更新某个指定产品的信息（提供该产品的部分字段信息）

DELETE https://api.example.com/v1/products/ID：删除某个指定产品

其他HTTP Methods：

• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是允许客户端可以改变的。

四、过滤参数

所有非资源主键过滤的条件放URL参数上，如返回条数，页数，排序，以及其他字段的条件过滤，例如：

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置。

?page=2&per_page=100：指定第几页，以及每页的记录数。

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

?product_type=1：指定筛选条件

五、HTTP CODE（响应码）

服务器返回的常用HTTP状态码，括号中是该状态码对应的HTTP Methods：

• 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
• 204 NO CONTENT - [DELETE]：用户删除数据成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
• 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
• 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
• 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

完整的HTTP CODE参见：

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

六、响应结果

建议：针对外层系统，即前端APP，H5与API层交互的情况，只要API接口成功接到请求，就不能返回200以外的HTTP状态。

1. 为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。接口返回模板：

   { status：200， data:{}||[]，msg:’’}

   status：接口的HTTP响应的状态，其值为响应的HTTP CODE。

   data：接口的主数据，可以根据实际返回数组或JSON对象。

   msg：信息，针对不同HTTP CODE相应在返回信息。

2. 针对不同操作，服务器响应状态为200时，向用户返回的结果，即上面数据结构中的data值应该符合以下规范：
   • GET /collection：返回资源对象的列表（数组）
   • GET /collection/resource：返回单个资源对象
   • POST /collection：返回新生成的资源对象
   • PUT /collection/resource：返回完整的资源对象
   • PATCH /collection/resource：返回完整的资源对象
   • DELETE /collection/resource：返回一个空的JSON{}

七、错误处理

建议：针对内部服务，使用原本HTTP CODE响应，不要使用上面处理为200的方式。

所有的异常都应该被映射到error payloads中，例如下面error payload模板：

{
  "errors"：[
    {
      "userMessage"："对不起，您请求的内容不存在！",
      "internalMessage"："No product found in the database",
      "code"：1234,
      "more info"："http://dev.mwaysolutions.com/blog/api/v1/errors/1234"
    }
  ]
}

userMessage：给前端使用的消息

internalMessage：服务器内部错误消息

code：该系统自定义的错误码

more info：统一管理系统错误及错误详情的地方

八、客户端调用

限制使用：Http Client，Feign。

 

 

九、消息体

通过POST方法提交的内容，必须遵循W3C规范，内容与Content-Type头部声明一一对应。

如内容为JSON，则Content-Type必须为application/json，不允许存在Content-Type为application/x-www-form-urlencoded但内容为JSON的非标使用。

 

HTTP INVOKE模式（即提供SDK的方式）

开发规范

服务端：

• 创建相应的DTO（如果需要用到的话）
• 创建服务接口
• 创建服务接口的具体实现类
• 公开服务

SDK：

• 创建相应的DTO（如果需要用到的话）
• 创建服务接口
• 访问服务

注意：服务端与SDK的DTO包名、类名、字段名都必须一样。服务接口一样