RESTful 接口设计开发规范

API 接口可以说是软件开发人员的用户界面，API 设计也是系统架构的重要环节。尤其对复杂和分布式系统而言，其设计的好坏，直接影响着整个系统的设计，实现和演进。一套糟糕的 API 设计也会严重影响使用者（开发人员）的心情和工作效率。

1. 使用HTTP Methods构建RESTful API

在HTTP协议中一共有九个HTTP Methods定义，分别是 GET、HEAD、POST、PUT、DELETE、TRACE、OPTIONS、CONNECT、PATCH，每个Http Method代表不同的用途和约定。在RESTful API 设计中，常用的有POST、GET、PUT、PATCH 和 DELETE，分别对应对资源的创建，获取，修改，部分修改和删除操作。下表简单列出了这些Methods的用途和返回值约定。这是一个推荐的API设计与开发的最佳实践和大多数现有 API 所遵守的约定。它本身并不是一个规范和强制标准。遵守约定和套路的好处是可以避免原则性设计缺陷，也可以让经常使用此类 API 的开发者感觉熟悉和容易上手，否则你可能需要额外的文档来解释你的特殊设计，增加了使用者的负担和学习成本。

序号	HTTP方法	操作方式	示例
1	POST	创建数据 Create	/users
2	GET	读取数据 Read	/users/{id} 取一条数据; /users?limit=1&offset=10 取多条数据
3	PUT	修改数据 Update; 整条修改; 修改除ID外的所有属性	/users/{id} 更新某一条数据
4	PATCH	修改数据 Update; 部分修改; 修改一条记录的部分属性	/users/{id} 更新部分数据
5	DELETE	删除数据 Delete	/users/{id} 删除某一条数据

其中 HEAD、TRACE、OPTIONS、CONNECT 在 RESTful API 设计中不常用，这些 Methods 具体定义可以在RFC2616规范中找到。如果需要，可以根据相关语意来实现具有对应功能的API。

2. API接口设计原则

• API 命名应该采用约定俗成的方式，保持简洁明了；

• 考虑到系统迭代和兼容性需求，API 中应该引入版本规则；

• 优雅的设计条件过滤、排序、搜索等传入参数形式；

• 合理设计返回数据的形式，格式和考虑启用压缩（GZIP）；数据返回结果建议使用JSON；

• 根据不同的 API 操作，设置合适的 HTTP 状态码和必要的出错信息；

• 使用 Token 机制设计鉴权和验证系统(Authorization and Authentication)

• 如何实现数据的分页返回；

• 如何处理有关联资源的返回数据；

• 考虑启用 HTTP 缓存机制，以改善网络通信效率；

• 无状态通信的会话状态应该全部由客户端负责维护；

• 分层系统通过限制组件的行为（即每个组件只能看到与其交互的紧邻层），将架构分解为若干等级的接口层；

• 限制 API 调用频次（Rate limiting）；

• 尽可能的使用 HTTPS，涉及用户验证的 API 一定要强制启用 HTTPS。

3. 使用HTTP状态码和错误响应

目前存在一种情况，有很多开发人员将API接口返回状态码一直设为200，然后在返回的数据里面自定义一些状态码来表示服务器返回结果的状态码。由于RESTful API是直接使用的HTTP协议，所以建议API接口的返回状态码也要尽量使用HTTP协议的状态码。以下是关于HTTP状态码和错误响应的建议：

1. 对于数据错误

• 400：请求信息不完整或无法解析。

• 422：请求信息完整，但无效。

• 404：资源不存在。

• 409：资源冲突。

2. 对于鉴权错误

• 401：访问令牌没有提供，或者无效。

• 403：访问令牌有效，但没有权限。

3. 对于标准状态

• 200： 所有的都正确。

• 500： 服务器内部抛出错误。