乐趣区

关于restful:开发出优秀的API构建RESTful-API的13种最佳实践

jiezi

首发于公众号《前端全栈开发者》，第一工夫浏览最新文章，会优先两天发表新文章。

Facebook、GitHub、Google 以及其余许多巨头都须要一种服务和生产数据的形式。在当今的开发环境中，RESTful API 依然是服务和生产数据的最佳抉择之一。

然而你是否思考过学习行业标准？设计 RESTful API 的最佳实际是什么？从实践上讲，任何人都能够在不到五分钟的工夫内疾速启动数据 API——无论是 Node.js，Golang 还是 Python。

咱们将探讨在构建 RESTful API 时应思考的 13 种最佳实际。但首先，让咱们疾速说明 RESTful API。

什么是 RESTful API？

RESTful API 须要满足以下束缚能力被称为 RESTful API。

  1. 客户端 - 服务器模型 ：RESTful API 遵循客户端 - 服务器模型，其中服务器为数据提供服务，而客户端连贯到服务器以应用数据。客户端和服务器之间的交互是通过 HTTP（S）申请进行的，该申请传输了申请的数据。
  2. 无状态 ：更重要的是，RESTful API 应该是无状态的。每个申请都被视为独立申请。服务器不应跟踪可能影响未来申请后果的任何外部状态。

  3. 对立接口 ：最初，一致性定义了客户端和服务器之间的交互方式。RESTful API 定义了命名资源的最佳实际，但定义了容许你批改资源 / 与之交互的固定 HTTP 操作。能够在 RESTful API 中拜访以下 HTTP 操作：

    • GET 申请：检索资源
    • POST 申请：创立资源或将信息发送到 API
    • PUT 申请：创立或替换资源
    • PATCH 申请：更新现有资源
    • DELETE 申请：删除资源

在对 RESTful API 的个性有了更深刻的理解后，是时候理解更多对于 RESTful API 的最佳实际了。

本文为你提供了 13 种最佳实际的可行清单。让咱们来摸索！

1. 正确应用 HTTP 办法

咱们曾经探讨了可用于批改资源的 HTTP 办法：GET，POST，PUT，PATCH 和 DELETE。

尽管如此，许多开发人员还是偏向于滥用 GET 和 POST 或 PUT 和 PATCH。通常，咱们看到开发人员应用 POST 申请来检索数据。此外，咱们看到开发人员应用 PUT 申请来替换资源，而他们只想更新该资源的单个字段。

确保应用正确的 HTTP 办法，因为这将为应用你的 RESTful API 的开发人员减少很多凌乱。最好是保持应用预约的准则。

2. 命名约定

理解 RESTful API 命名约定将对你有组织地设计 API 有很大帮忙。依据你服务的资源设计一个 RESTful API。

例如，你的 API 治理着作者和书籍（是的，一个经典的例子）。当初，咱们要增加一个新作者或拜访一个 ID 为 3 的作者。你能够设计上面的路由来达到这个目标：

  • api.com/addNewAuthor
  • api.com/getAuthorByID/3

设想一下，一个 API 承载了许多资源，每个资源都有许多属性。可能的端点列表将变得无穷无尽，而且对用户不是很敌对。所以咱们须要一种更有条理和标准化的形式来设计 API 端点。

RESTful API 最佳实际形容了端点应以资源名称结尾，而 HTTP 操作则形容操作。当初咱们失去：

  • POST api.com/authors
  • GET api.com/authors/3

如果咱们想拜访 ID 为 3 的作者已经写过的所有书籍怎么办？对于这种状况，RESTful API 也有解决办法：

  • GET api.com/authors/3/books

最初，如果您要为 ID 为 3 的作者删除 ID 为 5 的书，该怎么办？同样，让咱们遵循雷同的结构化办法来造成以下端点：

  • DELETE api.com/authors/3/books/5

简而言之，利用 HTTP 操作和资源映射的结构化形式来造成易于了解的端点门路。这种办法的最大长处是，每个开发人员都理解 RESTful API 的设计形式，他们能够立刻应用 API，而不用浏览你的每个端点的文档。

3. 应用复数资源

资源应始终应用其复数模式。为什么？假如你要检索所有作者。因而，你将调用以下端点：GET api.com/authors。

当你读取申请时，你无奈判断 API 响应是否只蕴含一个或所有作者。因而，API 端点应该应用复数资源。

4. 正确应用状态码

状态码在这里不只是为了好玩，它们有一个明确的目标，状态码告诉客户端申请的胜利。

最常见的状态码类别包含：

  • 200（OK）：申请已胜利解决并实现。
  • 201（Created）：批示胜利创立资源。
  • 400（Bad Request）：代表客户端谬误。也就是说，申请的格局不正确或短少申请参数。
  • 401（Unauthorized）：未受权，你尝试拜访你没有权限的资源。
  • 404（Not Found）：申请的资源不存在。
  • 500（Internal Server Error）：外部服务器谬误，服务器在执行申请期间引发异样。

状态码的残缺列表能够在 Mozilla Developers 找到。

5. 遵循雷同约定

最常见的是，RESTful API 提供 JSON 数据，因而，应遵循 camelCase 大小写常规。然而，不同的编程语言应用不同的命名约定。

6. 如何解决搜寻，分页，过滤和排序

搜寻，分页，过滤和排序等操作并不代表独自的端点。这些操作能够通过应用随 API 申请提供的查问参数来实现。

例如，让咱们检索按名称升序排列的所有作者。你的 API 申请应如下所示：api.com/authors?sort=name_asc。

此外，我想检索一个名称为“Michiel”的作者。该申请看起来像这样 api.com/authors?search=Michiel。

侥幸的是，许多 API 我的项目都带有内置的搜寻、分页、过滤和排序功能。这将为你节俭很多工夫。

7.API 版本控制

我不常看到这一点，但这是对你的 API 进行版本调整的最佳实际。这是一种无效的形式来向你的用户传播重大的变动。

通常，API 的版本号蕴含在 API URL 中，例如：api.com/v1/authors/3/books。

8. 通过 HTTP 标头发送元数据

HTTP 标头容许客户端随其申请发送其余信息。例如，Authorization 标头通常用于发送身份验证数据以拜访 API。

你能够在此处找到所有可能的 HTTP 标头的残缺列表。

9. 限速

速率限度是管制每个客户端申请数量的一种乏味办法。这些是服务器可能返回的速率限度标头：

  • X-Rate-Limit-Limit：通知客户端在指定工夫距离内能够发送的申请数。
  • X-Rate-Limit-Remaining：通知客户端在以后工夫距离内仍能够发送多少个申请。
  • X-Rate-Limit-Reset：通知客户端速率限度何时重置。

10. 有意义的错误处理

如果呈现问题，请务必向开发人员提供有意义的谬误音讯，这一点很重要。例如，Twilio API 返回以下谬误格局：

{
  "status": 400,
  "message": "Resource books does not exist",
  "code": 24801,
  "more_info": "api.com/docs/errors/24801"
}

在此示例中，服务器返回状态代码和人类可读的音讯。此外，还返回外部错误代码，供开发人员查找特定谬误，这使开发人员能够疾速查找无关该谬误的更多信息。

11. 抉择正确的 API 框架

存在许多用于不同编程语言的框架，抉择一个反对 RESTful API 最佳做法的框架十分重要。

对于 Node.js，后端开发人员喜爱应用 Express.js 和 Koa，而对于 Python，Falcon 是一个不错的抉择。

12. 文档化你的 API

最初，写文档！我不是在开玩笑，这依然是传递你新开发的 API 常识最简略的办法之一。

只管你的 API 遵循 RESTful API 列出的所有最佳实际，但依然值得你花工夫记录各种元素，比方 API 解决的资源或利用于服务器的速率限度。

想想你的其余开发人员，文档大大减少了学习 API 所需的工夫。

13. 把事件简单化！

不要让你的 API 过于简单，放弃资源简略。正确定义你的 API 解决的不同资源，将帮忙你在将来防止资源相干的问题。定义你的资源，还要精确定义它的属性和资源之间的关系。这样一来，如何连贯不同的资源就没有争议的空间了。

如果您喜爱这篇介绍 API 最佳实际的文章，那么您可能还喜爱从头开始学习构建 RESTful API。

退出移动版