之所以翻译这篇文章,是因为自从成为一名前端码农之后,调接口这件事情就成为了家常便饭,并且,还伴随着无数的争论与无奈。编写友好的 restful api
不论对于你的同事,还是将来作为第三方服务调用接口的用户来说,都显得至关重要。关于 restful api
本身以及设计原则,我陆陆续续也看过很多的文章和书籍,在读过原文后,感觉文中指出的 13 点最佳实践还是比较全面的且具有参考意义的,因此翻译出来分享给大家。如有错误,还望指正。
由于我一般倾向于意译,关于原文中的开头语或者一些与之无关的内容,我就省略掉了,毕竟时间是金钱,英语好并且能访问外国网站的朋友我建议还是看原文,以免造成理解上的误差。
如果你想要构建设计优良的 REST API,了解一些关于 HTTP 协议的基础知识是很有帮助的,毕竟磨刀不误砍材工。
在 MDN 上有很多质量不错的文档介绍 HTTP。但是,就 REST API 设计本身而言,所涉及到的 HTTP 知识要点大概包含以下几条:
GET
、POST
、PUT
、PATCH
还有 DELETE
是最常用的。/articles/
。GET: /articles/
。POST: /articles
可能代表“创建一个新的 article”。GET
代表查,POST
代表增,PUT
和 PATCH
代表改(注: PUT 通常代表整体更新,而 PATCH 代表局部更新),而 DELETE
代表删。当然了,你可以将 HTTP 协议中所提供的任何东西应用于 REST API 的设计之中,但以上这些是比较基础的,因此时刻将它们记在脑海中是很有必要的。
虽然返回 JSON 数据格式的数据不是 REST 架构规范强制限定的,但大多 REST API 都遵循这条准则。
但是,仅仅返回 JSON 数据格式的数据还是不够的,你还需要指定返回 body 的头部,比如 Content-Type
,它的值必须指定为 application/json
。这一点对于程序化客户端尤为重要(比如通过 python 的 requests
模块来与 api 进行交互)—— 这些程序是否对返回数据进行正确解码取决于这个头部。
注:通常而言,对于浏览器来说,这似乎不是问题,因为浏览器一般都自带内容嗅探机制,但为了保持一致性,还是在响应中设置这个头部比较妥当。
如果你理解了第 1 条最佳实践所传达的意思,那么你现在就会明白不要将动词放入 REST API 的 URI 中。这是因为 HTTP 的动词已经足以描述执行于资源的业务逻辑操作了。
举个例子,当你想要提供一个针对某个 article 提供 banner 图片并返回的接口时,可能会实现如下格式的接口:
GET: /articles/:slug/generateBanner/
这里 GET 已经说明了这个接口是在做读的操作,因此,可以简化为:
GET: /articles/:slug/banner/
类似的,如果这个端口是要创建一个 article:
// 不要这么做
POST: /articles/createNewArticle/
// 这才是最佳实践
POST: /articles/
尝试用 HTTP 的动词来描述所涉及的业务逻辑操作。
一些时候,使用资源的复数形式还是单数形式确实存在一定的困扰,比如使用 /article/:id/
更好还是使用 /articles/:id/
更好呢?
这里我推荐使用后者。为什么呢?因为复数形式可以满足所有类型端点的需求。
单数形式的 GET /article/2/
看起来还是不错的,但是如果是 GET /article/
呢?你能够仅通过字面信息来区分这个接口是返回某个 article 还是多个呢?
因此,为了避免有单数命名造成的歧义性,并尽可能的保持一致性,使用复数形式,比如:
GET: /articles/2/
POST: /articles/
...
当 API 服务器处理错误时,如果能够在返回的 JSON body 中包含错误信息,对于接口调用者来说,会一定程度上帮助他们完成调试。比如对于常见的提交表单,当遇到如下错误信息时:
{
"error": "Invalid payoad.",
"detail": {
"surname": "This field is required."
}
}
接口调用者很快就是明白发生错误的原因。
这一点可能是最重要、最重要、最重要的一点,可能也是这篇文章中,唯一你需要记住的那一点。
你可能知道,HTTP 中你可以返回带有 200 状态码的错误响应,但这是十分糟糕的。不要这么做,你应当返回与返回错误类型相一致的具有一定含义的状态码。
聪明的读者可能会说,我按照第 5 点最佳实践来提供足够详细的信息,难道不行吗?当然可以,不过让我讲一个故事:
我曾经使用过一个 API,对于它返回的所有响应的状态码均是 200 OK
,同时通过响应数据中的 status
字段来表示当前的请求是否成功,比如:
{
"status": "success",
"data": {}
}
所以,虽然状态码是 200 OK
,但我却不能绝对确定请求是否成功,事实上,当错误发生时,这个 API 会按如下代码片段返回响应:
HTTP/1.1 200 OK
Content-Type: text/html
{
"status": "failure",
"data": {
"error": "Expected at least two items in list."
}
}
头部还是 text/html
,因为它同时返回了一些 HTML 片段。
正因为这样,我不得不在检查响应状态码正确的同时,还需校验这个具有特殊含义的 status
字段的值,才可以放心的处理响应返回的 data
。
这种设计的一个真正坏处在于,它打破了接口与调用者之间的“信任”,因为你可能会担心这个接口对你撒谎(注:言外之意就是,由于特设的字段可能会改变,因此增加了不可靠性)。
所以,使用正确的状态码,同时仅在响应的 body 中返回错误信息,并设置正确的头部,比如:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Expected at least two items in list."
}
当你掌握了正确使用状态码之后,就应该努力使它们具有一致性。
比如,如果一个 POST 类型的端点返回 201 Created
,那么所有的 POST 端点都应返回同样的状态码。这样做的好处在于,调用者无需在意端点返回的状态码取决于某种特殊条件,也就形成了一致性。如果有特殊情况,请在文档中显著地说明它们。
下面是我推荐的与动词相对应的状态码:
GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
https://blog.florimondmanca.com/restful-api-design-13-best-practices-to-make-your-users-happy
使用 REST API 获取资源数据,通常情况下会直接获取多个或者单个,但当我们需要获取相关联的资源时,该怎么做呢?
比如说,我们期望获取作者为某个 author 的 article 列表 —— 假设 authro 的 id=12
。这里提供两种方案:
第一种方案通过在 URI 中,将嵌套的资源放在所关联的资源后边来进行描述,比如:
GET: /authors/12/articles/
一些人推荐这种方案的理由是,这种形式的 URI 一定程度上描述了 author 与 article 之间的一对多关系。但与此同时,结合第 4 点最佳实践,我们就不太能够分清当前端点返回的数据到底是 author 类型还是 article 类型。
这里有一篇文章,详细阐述了扁平化形式优于嵌套形式,因此一定有更好的方法,这就是下面的第二种方案:
GET: /articles/?author_id=12
直接将筛选 article 的逻辑抽离为 querystring 即可,这样的 URI 相比之前,更加清晰地描述了“获取所有 author(id=12) 的 article”的意思。
一个好的 URI 中是否应当包含尾部斜杠,并不具有探讨价值,选择一种更倾向的风格并保持一致性即可,同时当客户端误用尾部斜杠时,提供重定向响应。
我再来讲我自己的一个故事。某天,我在将某个 API 端点集成到项目中,但是我总是收到 500 Internal Error
的错误,我调用的端点差不多看起来这样:
POST: /entities
```
调试一段时间之后,我几乎崩溃了,因为我根本不知道我哪里做错了,直到我发现服务器之所以报 500 的错误,是因为我粗心丢掉了尾部斜杠(注:这种经历人人都会遇到,我在 SF 上遇过无数次类似的问题),当我把 URI 改成:
POST: /entities/
之后,一切正常运转。
当然,大多数的 web 框架都针对 URL 是否包含尾部斜杠,进行了优雅地处理并提供定制选项,如果可以的话,找到它并开启这项功能。
## 10. 使用 querystring 来完成筛选和分页功能
大部分情况下,一个简单的端点没有办法满足负责业务场景。
你的用户可能想要获取满足一定条件下的某些数据集合 ,同时为了保证性能,仅仅获取这个集合下的一个子集。换言之,这通常叫作**筛选**功能和**分页**功能:
* 筛选:用户可以提供额外的属性来控制返回的数据集合
* 分页:获取数据集合的子集,最简单的分页是基于分页个数的分页,它由 `page` 和 `page_size` 来决定
那么问题来了,我们如何将这两项功能与 RESTful API 结合在一起呢?
答案当然是通过 **querystring**。对于分页,很显然使用这种方式再合适不过了,比如:
GET: /articles/?page=1&page_size=10
但对于筛选,你可能会犯第 8 点最佳实践中所指出的问题,比如获取处于 published 状态的 article 列表:
GET: /articles/published/
除了之前提出的问题外,这里还涉及一个设计上的问题,就是 **published** 本身不是资源,它仅仅是资源的特征,类似这种特征字段,应该将它们放到 querystring 中:
GET: /articles/?published=true&page=2&page_size=20 `
更加优雅、清晰,不是吗?
当我们遇到 API 中关于安全的错误提示时,很容易混淆这两个不同类型的错误,认证和授权(比如权限相关)—— 老实讲,我自己也经常搞混。
这里是我自己总结的备忘录,它阐述了我如何在实际情况下,区分它们:
401 Unauthorized
)。403 Forbidden
)
我发现 202 Accepted
在某些场合是 201 Created
的一个非常便捷的替代方案,这个状态码的含义是:
服务器已经接受了你的请求,但是到目前为止还未创建新的资源,但一切仍处于正常状态。
我分享两种特别适合使用 202 Accepted
状态码的业务场景:
作为最后一个最佳实践,让我们来探讨这样一个问题:你如何在 API 的实施中,实践最佳实践呢?
通常的情况是这样的,你想要快速创建一个 API 以便一些服务可以互相访问彼此。Python 开发者可能马上掏出了 Flask,而 JS 开发者也不甘示弱,祭出了 Express,他们会使用实现一些简单的 routes 来处理 HTTP 请求。
但这样做的问题是,通常,web 框架并不是针对构建 REST API 服务而专门存在的,换言之,Flask 和 Express 是两个十分通用的框架,但它们并非特别适合用于构建 REST API 服务。因此,你必须采取额外的步骤来实施 API 中的最佳实践,但大多数情况下,由于懒惰或者时间紧张等因素,意味着你不会投入过多精力在这些方面 —— 然后给你的用户提供了一个古怪的 API 端点。
解决方案十分简单:工欲善其事,必先利其器,掌握并使用正确的工作才是最好的方案。在各种语言中,许多专门用于构建 REST API 服务的新框架已经出现了,它们可以帮助你在不牺牲生产力的情况下,轻松地完成工作,同时遵循最佳实践。在 Python 中,我发现的最好的 API 框架之一是 Falcon。它与 Flask 一样简单,非常高效,十分适合构建 REST API 服务。如果你更喜欢 Django 的话,使用 Django REST Framework就足够了,虽然框架不是那么直观(注:按我的理解应该是说不太容易上手,但是我不这么认为),但功能非常强大。在 NodeJS 中,Restify 似乎也是一个不错的选择,尽管我还没有尝试过。我强烈建议你给这些框架一个机会!它们将帮助你构建规范,优雅且设计良好的 REST API 服务。
我们都应致力于让调用 API 这件事成为一种乐趣。希望本文能使你了解到在构建更好的 REST API 服务的过程中,涉及到的一些建议和技巧。对我而言,应该把这些最佳实践归结为三点,分别是良好的语义,简洁和合理性。