13 个设计 REST API 的最佳实践

原文 RESTful API Design: 13 Best Practices to Make Your Users Happy

写在前面

之所以翻译这篇文章，是因为自从成为一名前端码农之后，调接口这件事情就成为了家常便饭，并且，还伴随着无数的争论与无奈。编写友好的 restful api 不论对于你的同事，还是将来作为第三方服务调用接口的用户来说，都显得至关重要。关于 restful api 本身以及设计原则，我陆陆续续也看过很多的文章和书籍，在读过原文后，感觉文中指出的 13 点最佳实践还是比较全面的且具有参考意义的，因此翻译出来分享给大家。如有错误，还望指正。

由于我一般倾向于意译，关于原文中的开头语或者一些与之无关的内容，我就省略掉了，毕竟时间是金钱，英语好并且能科学上网的朋友我建议还是看原文，以免造成理解上的误差。

1. 了解应用于 REST 之上的 HTTP 知识

如果你想要构建设计优良的 REST API，了解一些关于 HTTP 协议的基础知识是很有帮助的，毕竟磨刀不误砍材工。

在 MDN 上有很多质量不错的文档介绍 HTTP。但是，就 REST API 设计本身而言，所涉及到的 HTTP 知识要点大概包含以下几条：

• HTTP 中包含动词（或方法）： GET、POST、PUT、PATCH 还有 DELETE 是最常用的。
• REST 是面向资源的，一个资源被一个 URI 所标识，比如 /articles/。
• 端点（endpoint），一般指动词与 URI 的组合，比如 GET: /articles/。
• 一个端点可以被解释为对某种资源进行的某个动作。比如， POST: /articles 可能代表“创建一个新的 article”。
• 在业务领域，我们常常可以将动词和 CRUD（增删查改）关联起来：GET 代表查，POST代表增，PUT 和 PATCH 代表改（注: PUT 通常代表整体更新，而 PATCH 代表局部更新），而 DELETE 代表删。

当然了，你可以将 HTTP 协议中所提供的任何东西应用于 REST API 的设计之中，但以上这些是比较基础的，因此时刻将它们记在脑海中是很有必要的。

2. 不要返回纯文本

虽然返回 JSON 数据格式的数据不是 REST 架构规范强制限定的，但大多 REST API 都遵循这条准则。

但是，仅仅返回 JSON 数据格式的数据还是不够的，你还需要指定返回 body 的头部，比如 Content-Type，它的值必须指定为 application/json。这一点对于程序化客户端尤为重要（比如通过 python 的 requests 模块来与 api 进行交互）—— 这些程序是否对返回数据进行正确解码取决于这个头部。

注：通常而言，对于浏览器来说，这似乎不是问题，因为浏览器一般都自带内容嗅探机制，但为了保持一致性，还是在响应中设置这个头部比较妥当。

3. 避免在 URI 中使用动词

如果你理解了第 1 条最佳实践所传达的意思，那么你现在就会明白不要将动词放入 REST API 的 URI 中。这是因为 HTTP 的动词已经足以描述执行于资源的业务逻辑操作了。

举个例子，当你想要提供一个针对某个 article 提供 banner 图片并返回的接口时，可能会实现如下格式的接口：

GET: /articles/:slug/generateBanner/

这里 GET 已经说明了这个接口是在做读的操作，因此，可以简化为：

GET: /articles/:slug/banner/

类似的，如果这个端口是要创建一个 article:

// 不要这么做
POST: /articles/createNewArticle/

// 这才是最佳实践
POST: /articles/

尝试用 HTTP 的动词来描述所涉及的业务逻辑操作。

4. 使用复数的名词来描述资源

一些时候，使用资源的复数形式还是单数形式确实存在一定的困扰，比如使用 /article/:id/ 更好还是使用 /articles/:id/ 更好呢？

这里我推荐使用后者。为什么呢？因为复数形式可以满足所有类型端点的需求。

单数形式的 GET /article/2/ 看起来还是不错的，但是如果是 GET /article/ 呢？你能够仅通过字面信息来区分这个接口是返回某个 article 还是多个呢？

因此，为了避免有单数命名造成的歧义性，并尽可能的保持一致性，使用复数形式，比如：

GET: /articles/2/
POST: /articles/
...

5. 在响应中返回错误详情

当 API 服务器处理错误时，如果能够在返回的 JSON body 中包含错误信息，对于接口调用者来说，会一定程度上帮助他们完成调试。比如对于常见的提交表单，当遇到如下错误信息时：

{
    "error": "Invalid payoad.",
    "detail": {
        "surname": "This field is required."
    }
}

接口调用者很快就是明白发生错误的原因。

6. 小心 status code

这一点可能是最重要、最重要、最重要的一点，可能也是这篇文章中，唯一你需要记住的那一点。

你可能知道，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."
}

7. 保持 status code 的一致性

当你掌握了正确使用状态码之后，就应该努力使它们具有一致性。

比如，如果一个 POST 类型的端点返回 201 Created，那么所有的 POST 端点都应返回同样的状态码。这样做的好处在于，调用者无需在意端点返回的状态码取决于某种特殊条件，也就形成了一致性。如果有特殊情况，请在文档中显著地说明它们。

下面是我推荐的与动词相对应的状态码：

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

8. 不要嵌套资源

使用 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”的意思。

9. 优雅地处理尾部斜杠

一个好的 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

更加优雅、清晰，不是吗？

11. 分清 401 和 403

当我们遇到 API 中关于安全的错误提示时，很容易混淆这两个不同类型的错误，认证和授权（比如权限相关）—— 老实讲，我自己也经常搞混。

这里是我自己总结的备忘录，它阐述了我如何在实际情况下，区分它们：

• 用户是否未提供身份验证凭据？认证是否还有效？这种类型的错误一般是未认证（401 Unauthorized）。
• 用户经过了正常的身份验证，但没有访问资源所需的权限？这种一般是未授权（403 Forbidden）

12. 巧用 202 Accepted

我发现 202 Accepted 在某些场合是 201 Created 的一个非常便捷的替代方案，这个状态码的含义是：

服务器已经接受了你的请求，但是到目前为止还未创建新的资源，但一切仍处于正常状态。

我分享两种特别适合使用 202 Accepted 状态码的业务场景：

• 如果资源是经过位于将来一系列处理流程之后才创建的，比如当某项作业完成时
• 如果资源已经存在，但这是理想状态，因此不应该被识别为一个错误时

13. 采用 REST API 定制化的框架

作为最后一个最佳实践，让我们来探讨这样一个问题：你如何在 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 服务的过程中，涉及到的一些建议和技巧。对我而言，应该把这些最佳实践归结为三点，分别是良好的语义，简洁和合理性。

关注公众号 全栈101，只谈技术，不谈人生