WebAPI规范

WebAPI规范

一、协议

通常使用HTTPs协议

二、域名

1. API较简单，可将API放在主域名下，以固定prefix开头，例如：https://example.com/api/xxxx
2. API内容丰富，复杂多样，可将API部署在专属域名下，例如：https://api.example.com/

三、版本控制

使用场景

1. 客户端无法及时更新
   当应用客户端不能及时更新，为兼容客户端用户侧的使用，需要将接口版本化，以便不同版本的应用都能够正常使用；
2. 提供标准的第三方接口
   当需要向第三方提供标准接口时，鉴于长远的发展，功能的迭代更新，都必须要设置API版本控制；

使用方法

使用大版本URL形式，小版本Header形式，进行版本标识

1. URL标识形式
   大版本标识不向前兼容类型，比如方法的参数形式有了变化、方法名有了变等，不能与之前的API兼容的，采用URL标识形式，例如：http://example.com/api/v1/xxx;
2. Header标识形式
   小版本标识向前兼容类型，比如方法添加了参数，之前的方法不影响使用，仅通过Header的标识具体小版本即可，例如：Header内部 API-VERSION:1.2.1

四、URI设计

1. Http动词+宾语
   • GET：读取（Read）
   • POST：新建（Create）
   • PUT：更新（Update）
   • PATCH：更新（Update），通常是部分更新
   • DELETE：删除（Delete）
2. 宾语通常采用名词复数形式
   • 例如 GET /api/articles
   • 例如 DELETE /api/articles/{id}

五、状态码

需要针对每一个Request，给出HTTP状态码的反馈，不是正确错误都是200的响应，可以内部自定义业务code来表示具体的含义。

• 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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

六、结果响应

1. 响应Content-Type
   API通常以“application/json;charset=utf-8”的形式来响应接口，牺牲了少许网络传输的效率，大大提升结果的可读性，也是业内前后端交互认可的方式。
2. 方法响应结果规范

• GET /collection：返回资源对象的列表（数组）
• ​GET /collection/resource：返回单个资源对象
• ​POST /collection：返回新生成的资源对象
• ​PUT /collection/resource：返回完整的资源对象
• ​PATCH /collection/resource：返回完整的资源对象
• ​DELETE /collection/resource：返回一个空文档

参考列表

1. RESTful API 最佳实践
2. RESTful API 设计指南
3. 微软Web API设计
4. Architectural Styles and the Design of Network-based Software Architectures
5. REST in Practice