REST API接口设计最佳实践

这篇文章包含一些关于 REST 的注释以及我设计 RESTful API 时遵循的最佳实践，它将主要关注统一接口约束。

休息

REST（表述性状态转移）是 Roy Fielding 于 2000 年在其论文中提出的一种 Web 服务设计架构方法。RESTful API 是满足 REST 约束的 API。

约束

客户端-服务器 -分离客户端应用程序和服务器应用程序，这是关于关注点的分离，通过这样做，我们可以提高可移植性和可扩展性，因为它允许这些组件独立发展。
无状态——从客户端到服务器的每个请求都必须包含所有必要的信息，包括身份验证详细信息，服务器不能存储有关请求、会话、历史记录等的任何信息。
缓存 -当可能的响应数据必须可缓存时，客户端有权稍后重用响应数据。这将提高效率和可扩展性，但代价是，如果缓存的数据与服务器中的数据差异很大，则可能会降低可靠性。
统一接口 -定义并遵循 API 接口的标准，例如资源标识和响应消息。如果决定在 URI 中使用复数形式的资源名称，则所有 URI 都应遵循此标准，这将提高可读性和可维护性。
分层系统——系统必须由分层的组件构成，每个组件仅感知与其交互的直接层。例如，一个系统可以包含数据层、缓存层、安全层等。所有这些层级都不应影响服务器和客户端之间的通信。
按需代码 -这是唯一可选的约束，服务器将提供资源的静态表示，但在请求时它可以发送可执行代码。

在这篇文章中，我将展示一些实现统一界面的最佳实践，约束 1 和 2 非常简单，而其他约束有很多方法可以满足和涵盖它们，这超出了本文的范围。

设计API统一接口的最佳实践

REST 并不局限于 Web 应用程序，而且经常应用于 Web 应用程序，它利用 HTTP 协议。RESTful API 将通过一系列统一资源标识符 (URI) 来公开系统资源。响应将采用 JSON 或 XML 格式，您可以根据需要同时提供这两种格式，在这种情况下，客户端将使用 Content-Type 标头进行选择。定义好系统资源后，就该选择资源命名策略，并将其与 HTTP 方法结合使用，以表示对这些资源的操作。

此外，定义响应的标准也是明智之举：如果发生故障，响应主体会是什么？它会包含一条描述错误的消息，还是仅提供一个参考代码，还是两者兼而有之？如果成功，将呈现哪些资源数据？每个响应将使用哪些 HTTP 响应代码？这些问题必须在 API 设计阶段解决。

让我们以音乐流媒体服务为例，除了其他资源之外，它还包含艺术家、专辑和曲目，让我们看看定义 URI 的一些做法：

使用名词来表示资源，而不是动作

HTTP 方法将指示操作。

/** Do **/
api.example.com/artists

/** Don't **/
api.example.com/get-artists

多元化资源

这里的理由是我们正在处理资源集合。

/** Do **/
api.example.com/albums

/** Don't **/
api.example.com/album

展示资源之间的层次关系

这种策略提高了理解力。

api.example.com/artists/{id}/albums
api.example.com/artists/{id}/albums/{id}/tracks

这些 URI 表示艺术家拥有一系列专辑，而这些专辑又包含一系列曲目。这不是必需的，通常你会发现一些 API 不使用此格式，例如：

api.example.com/albums
api.example.com/albums/{id}/tracks

您可能会发现一些 API 同时提供这两种格式。另请注意，我们不使用尾部正斜杠，因为它不会增加语义值，例如：

api.example.com/artists/{id}/albums/

提高可读性的其他技巧

使用连字符（-）代替下划线（_）
仅使用小写字母
不要使用文件扩展名

使用HTTP方法来指示对资源的操作

最常见的 HTTP 方法

POST -创建资源
GET——读取资源
PUT——更新或替换资源
PATCH——修改资源
DELETE -删除资源

例子：

/** Get artists **/
GET api.example.com/artists

/** Get a particular artist **/
GET api.example.com/artists/{id}

/** Create a track **/
POST api.example.com/artists/{id}/albums/{id}/tracks

/** Update an album **/
PUT api.example.com/artists/{id}/albums/{id}

/** Delete a track **/
DELETE api.example.com/artists/{id}/albums/{id}/tracks/{id}

在响应中使用适当的 HTTP 响应代码

最常见的 HTTP 响应代码

200 OK -表示成功
201 Created -创建成功（通过 POST 或 PUT）
204 无内容 -表示成功，没有响应，但通常用于 DELETE 和 PUT 请求
400 错误请求 -表示请求存在问题，例如缺少信息或数据无效。
401 未授权 -表示身份验证凭据无效。
403 禁止 -用户无权执行该操作
404 未找到 -未找到资源
405 方法不允许 -表示 URL 存在，但 HTTP 方法不适用
500 内部错误 -表示服务器遇到错误，不知道如何处理

结论

这里描述的许多实践都来自于阅读、开发、集成以及阅读 API 文档。我认为遵循这些实践是创建简洁、连贯的 API 接口的好方法。

这篇文章只是略微涉及了一些内容，其他相关主题也值得探讨，例如缓存、压缩、安全、版本控制等等。为了更深入地了解，我推荐阅读以下内容：

了解其他 API 的设计方式也很有用，例如：

文章来源：https://dev.to/ricardo_borges/some-practices-to-design-restful-apis-interfaces-5a5i