1 使用描述性和有意义的资源名称

选择准确表示所代表实体的资源名称，不使用泛泛或模糊的名称。

2 正确使用 HTTP 方法

针对不同的操作使用适当的 HTTP 方法（GET、POST、PUT、DELETE、PATCH 等）。

图片

3 为 API 进行版本控制

通过版本控制来确保向后兼容性，同时能够在不破坏现有客户端的情况下进行未来的增强。

图片

4 正确使用 HTTP 状态码

返回适当的 HTTP 状态码来指示 API 请求的成功或失败。

图片

5 选择 JSON 字段命名约定（并坚持使用）

尽管 JSON 标准没有强制规定字段命名约定，但根据最佳实践，我们应该选择一种字段命名约定，并坚持使用。

图片

6 使用一致的错误消息

在大多数情况下，仅仅依靠HTTP状态码无法很好地解释错误的原因。为了帮助API使用者，应该提供结构化的JSON错误消息。这样可以更清楚地说明错误的具体原因。

响应应包含以下信息：

• 错误代码：一个机器可读的错误代码，用于标识具体的错误情况。
• 错误消息：一个人类可读的消息，提供详细的错误说明。
• 错误上下文：与错误相关的附加信息，例如请求 ID、导致错误的请求参数或导致错误的请求中的字段。
• 错误链接：指向资源或文档的 URL，提供关于错误以及如何解决错误的额外信息。
• 时间戳：错误发生的时间。

7 使用查询参数进行过滤、排序和搜索

查询参数支持在HTTP请求的URL中提供附加信息，以便控制服务器返回的响应。通过使用查询参数，可以定制您所需的特定结果。

图片

8 实现身份验证和授权

通过实施适当的身份验证和授权机制来保护 API。

• 对于身份验证使用 API 密钥、令牌或 OAuth 2.0。
• 对于授权应用基于角色的访问控制（RBAC）。

9 不要维护状态

REST API 不应该在服务器上维护状态，这是客户端的责任。

这一点非常重要，因为它使 API 可以进行缓存、可扩展，并且与客户端解耦。

例如，电子商务 API 可能使用 cookie 来维护购物车的状态。然而，这种方法违反了 RESTful API 的关键原则——它们需要是无状态的。

10 文档化 API

为 API 提供全面的文档，包括端点细节、请求/响应示例和使用指南。

• 使用 Swagger/OpenAPI 文档。
• 使用基于 Markdown 的文档（例如使用 Swagger UI 或 ReDoc 等工具）。