REST API设计最佳实践

设计人们会喜欢使用的REST API

一个设计良好的API用起来很愉快。它可预测、一致，并且按预期工作。REST（表述性状态转移）是设计API时最常见的架构风格，遵循其约定可以使您的API更易于学习、使用和维护。

以资源而非动作来思考

REST的核心思想是围绕资源来建模您的API——这些资源是您的系统管理的事物，如用户、订单、产品或文章。每个资源都有一个标识它的URL。您使用HTTP方法来指示您想要做什么：GET用于检索，POST用于创建，PUT用于替换，PATCH用于更新，DELETE用于删除。

URL应该是名词，而不是动词。使用/users而不是/getUsers，使用/orders而不是/createOrder。资源可以嵌套以显示关系：/users/123/orders表示属于用户123的订单。这使您的API直观——开发人员无需阅读文档即可猜测出URL。

正确使用HTTP状态码

HTTP状态码是您告诉客户端发生了什么的途径。200表示一切正常。201表示资源已创建（您应该包含指向它的Location头）。204表示请求成功但没有返回内容。400表示客户端发送了无效内容。401表示需要身份验证。403表示不允许。404表示未找到资源。429表示已受到速率限制。500表示服务器发生错误。

一致地使用正确的状态码可以使您的API更易于调试。客户端可以以编程方式处理错误，而不是解析错误消息。当HTTP客户端和API库等工具理解状态码时，它们可以提供更好的反馈。

从第一天开始就对API进行版本控制

即使您认为您的API是完美的，您最终也需要更改它。版本控制允许您在不破坏现有客户端的情况下进行更改。最简单的方法是将版本包含在URL中：/api/v1/users、/api/v2/users。当您需要进行重大更改时，创建一个新版本并给客户端迁移的时间。

一旦某个版本被弃用，请在响应中包含一个Sunset头，以警告客户端旧版本最终将被移除。这给了他们升级的时间。

处理分页、过滤和排序

当API返回资源列表时，它应该支持分页，以便客户端可以以可管理的块请求数据。对于大型数据集，基于游标的分页比基于页面的分页性能更好。允许客户端按常见字段过滤结果，并让他们指定排序顺序。在响应中包含元数据，以便客户端知道如何获取下一页。

返回一致的错误响应

当出现问题时，您的API应返回客户端可以解析的一致错误结构。包括错误代码、人类可读的消息以及有关出错原因的详细信息。对于验证错误，请指明哪个字段无效以及原因。有一种标准格式称为RFC 7807（HTTP API的问题详细信息），许多API都遵循此格式。

保护您的API

在Authorization头中使用Bearer令牌（如JWT）进行身份验证。使用API密钥进行服务器到服务器的通信。对于委托访问，实施OAuth 2.0。始终限制每个客户端的请求速率以防止滥用。并记录每个请求以进行审计和调试。

文档和测试

好的API是有文档的。OpenAPI规范（以前称为Swagger）是描述REST API的标准方式。工具可以从您的OpenAPI规范生成交互式文档、客户端库和测试套件。契约测试确保您的API如文档所述那样运行，而模拟服务器让客户端在API准备就绪之前就可以进行开发。