前言

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。

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