原文链接：https://www.sitepoint.com/build-restful-apis-best-practices/[1]
作者：https://www.sitepoint.com/author/mmulders/[2]
前言
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/addNewAuthorapi.com/getAuthorByID/3
想象一下，一个承载了许多资源的API，每个资源都有许多属性。可能的端点列表将变得无穷无尽，而且对用户不是很友好。所以我们需要一种更有组织、更标准化的方式来设计API端点。
RESTful API的最佳实践描述了一个端点应该以资源名称开始，而HTTP的操作则描述了行为。现在我们得到：
POST api.com/authorsGET 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[3]上找到。别忘了查看“I’m a teapot”状态码(418)。
遵循大小写约定
最常见的是，RESTful API提供JSON数据。因此，应该实行驼峰格式的大小写约定。然而，不同的编程语言使用不同的命名约定[4]。
如何处理搜索、分页、过滤和排序
搜索、分页、过滤和排序等操作并不代表单独的端点。这些操作可以通过使用与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头的完整列表可以在这里[5]找到。
速率限制
速率限制是一种有趣的方法，可以控制每个客户端的请求数量。下面这些是你的服务器可以返回的可能的速率限制头部：
X-Rate-Limit-Limit：告诉客户端在指定的时间间隔内可以发送的请求数量。X-Rate-Limit-Remaining：告诉客户端在当前时间间隔内还能发送多少个请求。X-Rate-Limit-Reset：告诉客户端何时重置速率限制。
有意义的错误处理
万一出了问题，向开发者提供一个有意义的错误信息是很重要的。比如说，Twilio的API返回以下错误格式：
代码语言：javascript复制{
"status": 400,
"message": "Resource books does not exist",
"code": 24801,
"more_info": "api.com/docs/errors/24801"
}
在这个例子中，服务器返回状态码和一个人类可读的信息。此外，还返回了一个内部错误代码，以便开发人员查找具体的错误。这允许开发人员快速查找有关该错误的更多信息。
选择正确的API框架
许多框架存在于不同的编程语言中。挑选一个支持RESTful API最佳实践的框架很重要。
对于Node.js，后端开发人员喜欢使用Express.js[6]，而对于Python，Falcon[7]是一个不错的选择。
输出文档
最后，就是编写文档！我没有在开玩笑。这仍然是传递关于你新开发的API知识的最简单的方法之一。
尽管你的API遵循了所有针对RESTful API的最佳实践，但仍然值得你花时间来记录各种元素。比如你的API处理的资源或你的服务器适用的速率限制。
想想你的开发同事们，文档大大减少了学习你的API所需的时间。
保持简洁
不要使你的API过于复杂，保持资源简洁。正确定义你的API所处理的不同资源将帮助你在未来避免与资源有关的问题。定义你的资源，还要准确定义它的属性和资源之间的关系。这样一来，在如何连接不同的资源上就没有争议的余地了。
总结
本文总结了13个构建RESTful API的最佳实践，分别是：
- 正确使用HTTP方法
- 命名约定
- 使用复数资源
- 正确使用状态码
- 遵循大小写约定
- 如何处理搜索、分页、过滤和排序
- API版本
- 通过HTTP头发送元数据
- 速率限制
- 有意义的错误处理
- 选择正确的API框架
- 输出文档
- 保持简洁
如果你喜欢这篇有关API最佳实践的文章，你可能也会喜欢学习从头开始建立一个RESTful API[8]。
以上就是全部内容，如果对你有所帮助，欢迎点赞收藏转发~
参考资料
[1]
https://www.sitepoint.com/build-restful-apis-best-practices/: https://www.sitepoint.com/build-restful-apis-best-practices/
[2]
https://www.sitepoint.com/author/mmulders/: https://www.sitepoint.com/author/mmulders/
[3]
MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
[4]
不同的命名约定: https://www.chaseadams.io/posts/most-common-programming-case-types/
[5]
这里: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields
[6]
Express.js: https://expressjs.com/
[7]
Falcon: https://falconframework.org/
[8]
从头开始建立一个RESTful API: https://www.sitepoint.com/build-rest-api-scratch-introduction/
