RESTful API设计-指南

​ Marius Masalar 在 Unsplash 上的照片

本文首发于微信公号软测小生 ruancexiaosheng

作为软件开发人员，我们大多数人在日常生活中使用或构建 REST api。APIs 是系统之间的默认通信方式。亚马逊是如何有效地使用 api 进行通信的最佳例子。

在这篇文章中，我将讨论如何更好地设计 RESTful api 以避免常见错误。

---

Jeff Bezos’ (成功的关键) 的指令

你们中的一些人可能已经知道Jeff Bezos对亚马逊开发者的授权。如果你没听过，以下几点是它的关键。

1. 因此，所有团队都将通过服务接口公开他们的数据和功能。
2. 团队之间必须通过这些接口进行沟通。
3. 不允许有其他形式的进程间通信，不允许直接链接，不允许直接读取另一个团队的数据存储，不允许共享内存模型，也不允许有后门。唯一允许的通信是通过网络上的服务接口调用。
4. 他们使用什么技术并不重要。HTTP 、 Corba 、 Pubsub 、自定义协议都不重要。Bezos不在乎。
5. 毫无例外，所有服务接口都必须从头开始设计，才能外部化。也就是说，团队必须进行规划和设计，以便能够向外部世界的开发人员公开接口。没有例外。
6. 任何不这样做的人都会被解雇。

最终，这被证明是亚马逊成功的关键。亚马逊可以构建可扩展的系统，之后还可以提供像亚马逊网络服务这样的服务。

---

RESTful api 的设计原则

现在，让我们来了解在设计 RESTful api 时应该遵循的原则。

保持精简

我们需要确保 API 的基本 URL 是简单的。例如，如果我们想为产品设计 api，它应该是这样设计的:

/products

/products/12345

第一个 API 是获取所有产品，第二个 API 是获取特定产品。

用名词(nouns)而不是动词(verbs)

很多开发者都犯了这个错误。他们通常忘记了我们有 HTTP 方法来更好地描述 API，并最终使用 API url 中的动词。例如，获取所有产品的 API 应该是:

/products

而不是如下所示

/getAllProducts

到目前为止，我已经看到了一些常见的 URL 模式。

使用正确的 HTTP 方法

RESTful API 有各种方法来指示我们将使用此 API 执行的操作类型。

• GET — 获取资源，请求指定的页面信息，并返回实体主体。
• POST — 创建资源，向指定资源提交数据进行处理请求（例如提交表单或者上传文件）。数据被包含在请求体中。POST 请求可能会导致新的资源的建立和/或已有资源的修改。
• PUT/PATCH — 更新现有资源，用来对已知资源进行局部更新 。
• DELETE — 删除现有资源，请求服务器删除指定的页面。

我们需要确保在给定的操作中使用正确的 HTTP 方法。

使用复数

这个话题有点争议。有些人喜欢保留带有复数名称的资源 URL，而另一些人喜欢保留单数。例如-

/products

/product

我喜欢保持它的复数，因为它避免了我们谈论的是获取单个资源还是集合的混淆。它还避免了添加额外的东西，将所有内容附加到基本 URL,比如 /product/all,有些人可能不喜欢这样，但我唯一的建议是在整个项目中保持统一。

使用参数

有时候，我们需要一个 API，它应该比仅仅通过 id 来讲述更多的故事。在这里，我们应该利用查询参数来设计 API。

• /products?name=’ABC’应该优先考虑 /getProductsByName
• /products?type=’xyz’ 应该优先考虑 /getProductsByType

这样，您就可以避免设计简单的长网址。

使用正确的 HTTP 代码

我们有很多 HTTP 代码。我们大多数人最终只使用了两种 200 和 500! 这当然不是一个好的做法。下面是一些常用的 HTTP 代码。

• 200 OK — 这是显示执行的操作成功的最常用的 HTTP 代码。
• 201 CREATED — 当您使用 POST 方法创建新资源时，可以使用此方法。
• 202 ACCEPTED —这可以用来确认发送给服务器的请求。
• 400 BAD REQUEST —当客户端输入验证失败时，可以使用此方法。
• 401 UNAUTHORIZED / 403 FORBIDDEN— 如果用户或系统无权执行某项操作，则可以使用此选项。
• 404 NOT FOUND— 如果您正在寻找某个资源，并且该资源在系统中不可用，则可以使用该资源。
• 500 INTERNAL SERVER ERROR — 这永远不应该被明确抛出，但是如果系统失败，可能会发生。
• 502 BAD GATEWAY — 如果服务器从上游服务器接收到无效响应，则可以使用此选项。

版本控制

Api 的版本控制非常重要。许多不同的公司以不同的方式使用版本。有些使用版本作为日期，有些使用版本作为查询参数。我通常喜欢在资源前面加上它。例如:

/v1/products

/v2/products

我也想避免使用 /v1.2/products, 这意味着 API 会经常变化。此外，在 url 中可能不容易看到点 (.)。所以保持精简。

保持向后兼容性总是一个很好的做法，这样如果你改变 API 版本，消费者就有足够的时间进入下一个版本。

使用分页

当您公开可能返回大量数据的 API 时，必须使用分页，如果没有进行适当的负载平衡，消费者可能最终会关闭服务。我们需要始终记住，API 设计应该是完整的证明和傻瓜证明。

这里建议使用 limit和 offset.例如:, /products?limit=25&offset=50. 还建议保留默认限制和默认偏移。

支持的格式

选择 API 的响应方式也很重要。大多数现代应用程序都应该返回 JSON 响应，除非你有一个仍然需要获得 XML 响应的遗留应用程序。

使用正确的错误信息

保持应用程序发送的一组错误消息并以正确的 id 对其做出响应总是一个很好的做法。例如，如果您使用 Facebook graph APIs，如果出现错误，它会返回如下消息:

{

"error": {

"message": "(#803) Some of the aliases you requested do not exist: products",

"type": "OAuthException",

"code": 803,

"fbtrace_id": "FOXX2AhLh80"

}

}

我还看到了一些例子，在这些例子中，人们返回带有错误消息的 URL，这告诉你更多关于错误消息的信息以及如何处理它。

OpenAPI 规范的使用

为了让你公司的所有团队遵守某些原则，使用 OpenAPI 规范是很有用的。OpenAPI 允许您首先设计 api，并以更简单的方式与消费者分享。

结论：

很明显，如果你想更好地交流，api 是一条路。但是如果它们设计得不好，可能会增加混乱。因此，尽最大努力做好设计，剩下的只是实现。

​

---

感谢您的阅读

如果你遇到了一些更好的设计 api 的方法，请随时在评论部分分享这些方法。欢迎所有反馈!