关于restful:13个构建RESTful-API的最佳实践

前言

Facebook、GitHub、Google 和其余许多巨头都须要一种办法来服务和生产数据。在明天的开发环境中，RESTful API 依然是服务和生产数据的最佳抉择之一。

但你是否思考过学习行业标准？设计一个 RESTful API 的最佳实际是什么？实践上来说，任何人都能够在 5 分钟内疾速启动一个数据 API。无论是 Node.js、Golang，还是 Python。

咱们将摸索构建 RESTful API 时应该思考的 13 个最佳实际。

最佳实际

本文为你提供了 13 个可操作的最佳实际清单。让咱们一起来摸索吧！

正确应用 HTTP 办法

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

然而，许多开发者往往会滥用 GET 和 POST，或者 PUT 和 PATCH。通常状况下，咱们看到开发者应用 POST 申请来检索数据。此外，咱们看到开发者应用 PUT 申请来替换资源，而他们只想更新该资源的一个字段。

确保应用正确的 HTTP 办法。如若不如此做，将为应用你的 RESTful API 的开发者减少许多困惑。最好恪守预约的准则。

命名约定

了解 RESTful API 的命名约定将对你井井有条地设计你的 API 有很大的帮忙。依据你所服务的资源来设计一个 RESTful API。

举例来说，你的 API 用来治理作者和书籍（没错，十分经典的例子）。当初，咱们想增加一位新作者，或者通过 ID3来拜访一位作者。你能够设计以下路由来实现此目标：

• 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，而不用浏览你的每个端点的文档。

应用复数资源

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

当你浏览申请时，你无奈判断 API 响应将只蕴含一个或所有作者。出于这个起因，API 端点应该应用复数资源。

正确应用状态码

状态码不仅仅是为了好玩，他们有明确的目标。状态码告诉客户端申请胜利。

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

• 200 (OK)：申请已胜利解决并实现。
• 201 (Created)：示意资源创立胜利。
• 400 (Bad Request)：示意客户端谬误。也就是说，申请格局不正确或短少申请参数。
• 401 (Unauthorized)：尝试拜访没有权限的资源。
• 404 (Not Found)：申请的资源不存在。
• 500 (Internal Server Error)：每当服务器在申请执行过程中引发异样时。

状态码的残缺列表能够在 MDN 上找到。别忘了查看“I’m a teapot”状态码(418)。

遵循大小写约定

最常见的是，RESTful API 提供 JSON 数据。因而，应该履行驼峰格局的大小写约定。然而，不同的编程语言应用不同的命名约定。

如何解决搜寻、分页、过滤和排序

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

比如说，让咱们检索所有依照姓名升序排序的作者。你的 API 申请看起来应该长这样：api.com/authors?sort=name_asc。

此外，我想检索名为 Michiel 的作者。申请看起来长这样：api.com/authors?search=Michiel。

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

API 版本

我并不常常看到这种状况，但这是对 API 进行版本化的最佳实际。这是向用户传播破坏性更改的无效办法。

通常，API 的版本号被纳入 API 的 URL 中，比方：api.com/v1/authors/3/books。

通过 HTTP 头发送元数据

HTTP 头容许客户在其申请中发送额定的信息。例如，Authorization头部通常用于发送认证数据以拜访 API。

所有可能的 HTTP 头的残缺列表能够在这里找到。

速率限度

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

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

有意义的错误处理

万一出了问题，向开发者提供一个有意义的错误信息是很重要的。比如说，Twilio 的 API 返回以下谬误格局：

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

在这个例子中，服务器返回状态码和一个人类可读的信息。此外，还返回了一个外部错误代码，以便开发人员查找具体的谬误。这容许开发人员疾速查找无关该谬误的更多信息。

抉择正确的 API 框架

许多框架存在于不同的编程语言中。筛选一个反对 RESTful API 最佳实际的框架很重要。

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

输入文档

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

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

想想你的开发共事们，文档大大减少了学习你的 API 所需的工夫。

放弃简洁

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

总结

本文总结了 13 个构建 RESTful API 的最佳实际，别离是：

• 正确应用 HTTP 办法
• 命名约定
• 应用复数资源
• 正确应用状态码
• 遵循大小写约定
• 如何解决搜寻、分页、过滤和排序
• API 版本
• 通过 HTTP 头发送元数据
• 速率限度
• 有意义的错误处理
• 抉择正确的 API 框架
• 输入文档
• 放弃简洁

如果你喜爱这篇无关 API 最佳实际的文章，你可能也会喜爱学习从头开始建设一个 RESTful API。

以上就是全部内容，如果对你有所帮忙，欢送点赞珍藏转发~