Facebook、GitHub、google以及其他许多巨头都需要一种服务和消费数据的方式。在当今的开发环境中,RESTful API仍然是服务和消费数据的最佳选择之一。
但是你是否考虑过学习行业标准?设计RESTful API的最佳实践是什么?从理论上讲,任何人都可以在不到五分钟的时间内快速启动数据API——无论是Node.js,Golang还是Python。
我们将探讨在构建RESTful API时应考虑的13种最佳实践。但首先,让我们快速阐明RESTful API。
RESTful API需要满足以下约束才能被称为RESTful API。
在对RESTful API的特性有了更深入的了解后,是时候了解更多关于RESTful API的最佳实践了。
本文为你提供了13种最佳实践的可行清单。让我们来探索!
我们已经讨论了可用于修改资源的HTTP方法:GET,POST,PUT,PATCH和DELETE。
尽管如此,许多开发人员还是倾向于滥用GET和POST或PUT和PATCH。通常,我们看到开发人员使用POST请求来检索数据。此外,我们看到开发人员使用PUT请求来替换资源,而他们只想更新该资源的单个字段。
确保使用正确的HTTP方法,因为这将为使用你的RESTful API的开发人员增加很多混乱。最好是坚持使用预定的准则。
了解RESTful API命名约定将对你有组织地设计API有很大帮助。根据你服务的资源设计一个RESTful API。
例如,你的API管理着作者和书籍(是的,一个经典的例子)。现在,我们要添加一个新作者或访问一个ID为 3 的作者。你可以设计下面的路由来达到这个目的:
想象一下,一个API承载了许多资源,每个资源都有许多属性。可能的端点列表将变得无穷无尽,而且对用户不是很友好。所以我们需要一种更有条理和标准化的方式来设计API端点。
RESTful API最佳实践描述了端点应以资源名称开头,而HTTP操作则描述操作。现在我们得到:
如果我们想访问ID为 3 的作者曾经写过的所有书籍怎么办?对于这种情况,RESTful API也有解决办法:
最后,如果您要为ID为 3 的作者删除ID为 5 的书,该怎么办?同样,让我们遵循相同的结构化方法来形成以下端点:
简而言之,利用HTTP操作和资源映射的结构化方式来形成易于理解的端点路径。这种方法的最大优点是,每个开发人员都了解RESTful API的设计方式,他们可以立即使用API,而不必阅读你的每个端点的文档。
资源应始终使用其复数形式。为什么?假设你要检索所有作者。因此,你将调用以下端点:GET api.com/authors。
当你读取请求时,你无法判断API响应是否只包含一个或所有作者。因此,API端点应该使用复数资源。
状态码在这里不只是为了好玩,它们有一个明确的目的,状态码通知客户端请求的成功。
最常见的状态码类别包括:
状态码的完整列表可以在Mozilla Developers找到。
最常见的是,RESTful API提供JSON数据,因此,应遵循camelCase大小写惯例。但是,不同的编程语言使用不同的命名约定。
搜索,分页,过滤和排序等操作并不代表单独的端点。这些操作可以通过使用随API请求提供的查询参数来完成。
例如,让我们检索按名称升序排列的所有作者。你的API请求应如下所示:api.com/authors?sort=name_asc。
此外,我想检索一个名称为“ Michiel”的作者。该请求看起来像这样 api.com/authors?search=Michiel。
幸运的是,许多API项目都带有内置的搜索、分页、过滤和排序功能。这将为你节省很多时间。
我不常看到这一点,但这是对你的API进行版本调整的最佳实践。这是一种有效的方式来向你的用户传达重大的变化。
通常,API的版本号包含在API URL中,例如:api.com/v1/authors/3/books。
HTTP标头允许客户端随其请求发送其他信息。例如,Authorization 标头通常用于发送身份验证数据以访问API。
你可以在此处找到所有可能的HTTP标头的完整列表。
速率限制是控制每个客户端请求数量的一种有趣方法。这些是服务器可能返回的速率限制标头:
如果出现问题,请务必向开发人员提供有意义的错误消息,这一点很重要。例如,Twilio API返回以下错误格式:
{
"status": 400,
"message": "Resource books does not exist",
"code": 24801,
"more_info": "api.com/docs/errors/24801"
}
在此示例中,服务器返回状态代码和人类可读的消息。此外,还返回内部错误代码,供开发人员查找特定错误,这使开发人员可以快速查找有关该错误的更多信息。
存在许多用于不同编程语言的框架,选择一个支持RESTful API最佳做法的框架非常重要。
对于Node.js,后端开发人员喜欢使用Express.js和Koa,而对于Python,Falcon是一个不错的选择。
最后,写文档!我不是在开玩笑,这仍然是传递你新开发的API知识最简单的方法之一。
尽管你的API遵循RESTful API列出的所有最佳实践,但仍然值得你花时间记录各种元素,比如API处理的资源或应用于服务器的速率限制。
想想你的其他开发人员,文档大大减少了学习API所需的时间。
不要让你的API过于复杂,保持资源简单。正确定义你的API处理的不同资源,将帮助你在未来避免资源相关的问题。定义你的资源,还要准确定义它的属性和资源之间的关系。这样一来,如何连接不同的资源就没有争议的空间了。