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 等工具）。
