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。

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