【译】构建RESTful API的13种最佳实践
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 遵循客户端-服务器模型,其中服务器为数据提供服务,而客户端连接到服务器以使用数据。客户端和服务器之间的交互是通过 HTTP(S)请求进行的,该请求传输了请求的数据。
- 无状态:更重要的是,RESTful API 应该是无状态的。每个请求都被视为独立请求。服务器不应跟踪可能影响将来请求结果的任何内部状态。
- 统一接口:最后,一致性定义了客户端和服务器之间的交互方式。RESTful API 定义了命名资源的最佳实践,但定义了允许你修改资源/与之交互的固定 HTTP 操作。可以在 RESTful API 中访问以下 HTTP 操作:
- GET 请求:检索资源
- POST 请求:创建资源或将信息发送到 API
- PUT 请求:创建或替换资源
- PATCH 请求:更新现有资源
- DELETE 请求:删除资源
在对 RESTful API 的特性有了更深入的了解后,是时候了解更多关于 RESTful API 的最佳实践了。
本文为你提供了 13 种最佳实践的可行清单。让我们来探索!
1.正确使用 HTTP 方法
我们已经讨论了可用于修改资源的 HTTP 方法:GET,POST,PUT,PATCH 和 DELETE。
尽管如此,许多开发人员还是倾向于滥用 GET 和 POST 或 PUT 和 PATCH。通常,我们看到开发人员使用 POST 请求来检索数据。此外,我们看到开发人员使用 PUT 请求来替换资源,而他们只想更新该资源的单个字段。
确保使用正确的 HTTP 方法,因为这将为使用你的 RESTful API 的开发人员增加很多混乱。最好是坚持使用预定的准则。
2.命名约定
了解 RESTful API 命名约定将对你有组织地设计 API 有很大帮助。根据你服务的资源设计一个 RESTful API。
例如,你的 API 管理着作者和书籍(是的,一个经典的例子)。现在,我们要添加一个新作者或访问一个 ID 为 3
的作者。你可以设计下面的路由来达到这个目的:
- 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,而不必阅读你的每个端点的文档。
3.使用复数资源
资源应始终使用其复数形式。为什么?假设你要检索所有作者。因此,你将调用以下端点:GET api.com/authors
。
当你读取请求时,你无法判断 API 响应是否只包含一个或所有作者。因此,API 端点应该使用复数资源。
4.正确使用状态码
状态码在这里不只是为了好玩,它们有一个明确的目的,状态码通知客户端请求的成功。
最常见的状态码类别包括:
- 200(OK):请求已成功处理并完成。
- 201(Created):指示成功创建资源。
- 400(Bad Request):代表客户端错误。也就是说,请求的格式不正确或缺少请求参数。
- 401(Unauthorized):未授权,你尝试访问你没有权限的资源。
- 404(Not Found):请求的资源不存在。
- 500(Internal Server Error):内部服务器错误,服务器在执行请求期间引发异常。
状态码的完整列表可以在Mozilla Developers找到。
5.遵循相同约定
最常见的是,RESTful API 提供 JSON 数据,因此,应遵循 camelCase 大小写惯例。但是,不同的编程语言使用不同的命名约定。
6.如何处理搜索,分页,过滤和排序
搜索,分页,过滤和排序等操作并不代表单独的端点。这些操作可以通过使用随 API 请求提供的查询参数来完成。
例如,让我们检索按名称升序排列的所有作者。你的 API 请求应如下所示:api.com/authors?sort=name_asc
。
此外,我想检索一个名称为“ Michiel”的作者。该请求看起来像这样 api.com/authors?search=Michiel
。
幸运的是,许多 API 项目都带有内置的搜索、分页、过滤和排序功能。这将为你节省很多时间。
7.API 版本控制
我不常看到这一点,但这是对你的 API 进行版本调整的最佳实践。这是一种有效的方式来向你的用户传达重大的变化。
通常,API 的版本号包含在 API URL 中,例如:api.com/v1/authors/3/books
。
8.通过 HTTP 标头发送元数据
HTTP 标头允许客户端随其请求发送其他信息。例如,Authorization
标头通常用于发送身份验证数据以访问 API。
你可以在此处找到所有可能的 HTTP 标头的完整列表。
9.限速
速率限制是控制每个客户端请求数量的一种有趣方法。这些是服务器可能返回的速率限制标头:
-
X-Rate-Limit-Limit
:告诉客户端在指定时间间隔内可以发送的请求数。 -
X-Rate-Limit-Remaining
:告诉客户端在当前时间间隔内仍可以发送多少个请求。 -
X-Rate-Limit-Reset
:告诉客户端速率限制何时重置。
10.有意义的错误处理
如果出现问题,请务必向开发人员提供有意义的错误消息,这一点很重要。例如,Twilio API 返回以下错误格式:
{
"status": 400,
"message": "Resource books does not exist",
"code": 24801,
"more_info": "api.com/docs/errors/24801"
}
在此示例中,服务器返回状态代码和人类可读的消息。此外,还返回内部错误代码,供开发人员查找特定错误,这使开发人员可以快速查找有关该错误的更多信息。
11.选择正确的 API 框架
存在许多用于不同编程语言的框架,选择一个支持 RESTful API 最佳做法的框架非常重要。
对于 Node.js,后端开发人员喜欢使用 Express.js 和 Koa,而对于 Python,Falcon 是一个不错的选择。
12.文档化你的 API
最后,写文档!我不是在开玩笑,这仍然是传递你新开发的 API 知识最简单的方法之一。
尽管你的 API 遵循 RESTful API 列出的所有最佳实践,但仍然值得你花时间记录各种元素,比如 API 处理的资源或应用于服务器的速率限制。
想想你的其他开发人员,文档大大减少了学习 API 所需的时间。
13.把事情简单化!
不要让你的 API 过于复杂,保持资源简单。正确定义你的 API 处理的不同资源,将帮助你在未来避免资源相关的问题。定义你的资源,还要准确定义它的属性和资源之间的关系。这样一来,如何连接不同的资源就没有争议的空间了。
如果您喜欢这篇介绍 API 最佳实践的文章,那么您可能还喜欢从头开始学习构建 RESTful API。
原文:https://www.sitepoint.com/build-restful-apis-best-practices/
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- linux systemctl命令详解
- CentOS7使用dnf安装mysql的方法
- Linux中crontab定时任务不执行的原因
- Linux系统为什么要吃掉我的“内存”
- 教你如何修改Linux远程登录欢迎提示信息
- 详解linux 定时任务 crontabs 安装及使用方法
- 解决Centos7安装nginx后提示“Welcome to nginx on Fedora!”,conf.d目录下无default.conf文件
- 详解Linux中PostgreSQL和PostGIS的安装和使用
- 检测ip和port是否可连接的方法
- Linux关机时执行指定脚本功能实现
- 适用于稀疏的嵌入、独热编码数据的损失函数回顾和PyTorch实现
- CentOS7下实现终端输入中文设置详解
- CentOS 7.2搭建VNC远程桌面服务的方法
- Ubuntu挂载3T硬盘或大于2T磁盘的方法
- linux chroot命令详解