共计 3174 个字符，预计需要花费 8 分钟才能阅读完成。
翻译：Eolinker
起源：www.eolinker.com
Facebook、GitHub、Google 以及其余许多巨头都须要一种服务和生产数据的形式。在当今的开发环境中，RESTful API 依然是服务和生产数据的最佳抉择之一。
然而你是否思考过学习行业标准？设计 RESTful API 的最佳实际是什么？从实践上讲，任何人都能够在不到五分钟的工夫内疾速启动数据 API——无论是 Node.js，Golang 还是 Python。
咱们将探讨在构建 RESTful API 时应思考的 13 种最佳实际。
什么是 RESTful API？
RESTful API 须要满足以下束缚能力被称为 RESTful API。
- 客户端 - 服务器模型：RESTful API 遵循客户端 - 服务器模型，其中服务器为数据提供服务，而客户端连贯到服务器以应用数据。客户端和服务器之间的交互是通过 HTTP（S）申请进行的，该申请传输了申请的数据。
- 无状态：更重要的是，RESTful API 应该是无状态的。每个申请都被视为独立申请。服务器不应跟踪可能影响未来申请后果的任何外部状态。
- 对立接口：最初，一致性定义了客户端和服务器之间的交互方式。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[1]找到。
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。
你能够在此处 [2] 找到所有可能的 HTTP 标头的残缺列表。
9. 限速
速率限度是管制每个客户端申请数量的一种乏味办法。这些是服务器可能返回的速率限度标头：
• X-Rate-Limit-Limit：通知客户端在指定工夫距离内能够发送的申请数。
• X-Rate-Limit-Remaining：通知客户端在以后工夫距离内仍能够发送多少个申请。
• X-Rate-Limit-Reset：通知客户端速率限度何时重置。
•
10. 有意义的错误处理
如果呈现问题，请务必向开发人员提供有意义的谬误音讯，这一点很重要。例如，Twilio API 返回以下谬误格局：
在此示例中，服务器返回状态代码和人类可读的音讯。此外，还返回外部错误代码，供开发人员查找特定谬误，这使开发人员能够疾速查找无关该谬误的更多信息。
11. 抉择正确的 API 框架
存在许多用于不同编程语言的框架，抉择一个反对 RESTful API 最佳做法的框架十分重要。
对于 Node.js，后端开发人员喜爱应用 Express.js 和 Koa，而对于 Python，Falcon 是一个不错的抉择。
12. 文档化你的 API
最初，写文档！我不是在开玩笑，这依然是传递你新开发的 API 常识最简略的办法之一。
只管你的 API 遵循 RESTful API 列出的所有最佳实际，但依然值得你花工夫记录各种元素，比方 API 解决的资源或利用于服务器的速率限度。
想想你的其余开发人员，文档大大减少了学习 API 所需的工夫。
13. 把事件简单化！
不要让你的 API 过于简单，放弃资源简略。正确定义你的 API 解决的不同资源，将帮忙你在将来防止资源相干的问题。定义你的资源，还要精确定义它的属性和资源之间的关系。这样一来，如何连贯不同的资源就没有争议的空间了。