前言
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。
以上就是全部内容,如果对你有所帮助,欢迎点赞收藏转发~