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

以上就是全部内容,如果对你有所帮助,欢迎点赞收藏转发~

你可能感兴趣的:(restful)