选择准确表示所代表实体的资源名称,不使用泛泛或模糊的名称。
针对不同的操作使用适当的 HTTP 方法(GET、POST、PUT、DELETE、PATCH 等)。
图片
通过版本控制来确保向后兼容性,同时能够在不破坏现有客户端的情况下进行未来的增强。
图片
返回适当的 HTTP 状态码来指示 API 请求的成功或失败。
图片
尽管 JSON 标准没有强制规定字段命名约定,但根据最佳实践,我们应该选择一种字段命名约定,并坚持使用。
图片
在大多数情况下,仅仅依靠HTTP状态码无法很好地解释错误的原因。为了帮助API使用者,应该提供结构化的JSON错误消息。这样可以更清楚地说明错误的具体原因。
响应应包含以下信息:
查询参数支持在HTTP请求的URL中提供附加信息,以便控制服务器返回的响应。通过使用查询参数,可以定制您所需的特定结果。
图片
通过实施适当的身份验证和授权机制来保护 API。
REST API 不应该在服务器上维护状态,这是客户端的责任。
这一点非常重要,因为它使 API 可以进行缓存、可扩展,并且与客户端解耦。
例如,电子商务 API 可能使用 cookie 来维护购物车的状态。然而,这种方法违反了 RESTful API 的关键原则——它们需要是无状态的。
为 API 提供全面的文档,包括端点细节、请求/响应示例和使用指南。