【API架构】使用 JSON API 的好处

架构师研究会

发布于 2022-05-29 03:58:48

2.9K00

代码可运行

文章被收录于专栏：超级架构师超级架构师

运行总次数：0

代码可运行

在 API 工艺的世界里，没有比设计更受热议的领域了。从 REST、gRPC 到 GraphQL，有许多方法可以设计和标准化 Web API 交互。今天，我们将注意力转向另一种方法，JSON API，JSONAPI.org 上详细介绍的用于构建 API 的规范。

JSONAPI.org 中描述的 JSON API 非常适合使您的 JSON 响应格式更加一致。以提高生产力和效率为目标，JSON API 因其可以消除多余的服务器请求的高效缓存功能而受到吹捧。

在这篇文章中，我们将定义 JSON API 是什么，并了解如何使用它来构建高效的 API。我们将介绍 JSON API 的一些主要优点，并通过 FitBit 的案例研究了解该规范在实践中的应用情况。希望本概述将介绍 JSON API 的新手，并帮助您判断它是否适合您的 API 场景。

什么是 JSON API (JSONAPI.org)？

JSON API 是一种适用于 HTTP 的格式。它描述了客户端应如何从服务器请求或编辑数据，以及服务器应如何响应所述请求。该规范的一个主要目标（现在是稳定的 v1.0）是优化 HTTP 请求；在请求数量和客户端和服务器之间交换的数据包大小方面。

“JSON API 是一种有线(Wire)协议，用于通过 HTTP 增量获取和更新图形” ——耶胡达·卡茨

在 JSON API 中，客户端和服务器都在请求文档中发送 JSON API 数据，带有以下标头，而不指定媒体类型参数：

Content-Type: application/vnd.api+json

JSON API 表示如何调用资源以及如何共享相关链接。JSON 对象位于请求的根部，它必须包含资源数据、错误或元信息。数据以及与数据的关系可以通过 GET 调用来获取，如下所示：

GET /articles HTTP/1.1
Accept: application/vnd.api+json

以下是资源类型 `articles` 在 JSON API 响应中的显示方式：

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}
// ...

到目前为止，相当标准的东西。JSON API 支持创建、更新和删除资源的典型 CRUD 流程。JSON API 将始终向后兼容，它是一个社区驱动的计划，在 Github 上接受拉取请求。

使用 JSON API 的好处

既然我们对 JSON API 是什么有了基本的了解，那么有哪些独特的优势使它脱颖而出？

复合文档

复合文档是 JSON API 中的一项独特功能，允许服务器将相关资源与请求的主要资源一起发送——如果实施得当，这可以减少必要的 HTTP 请求的数量。复合文档使用 include 参数工作，如下所示：

GET https://api.example.com/posts?include=author

这使您能够在初始请求中包含其他资源。

稀疏字段集

如果您使用复合文档来包含相关资源，您可能会遇到回复量大的问题。再一次，JSON API 有一个解决方案。

JSON API 的另一个独特方面是稀疏字段集，它使客户端只能从特定字段请求数据。它通过将要检索的字段添加到具有资源名称和所需字段的 URI 参数来工作。这提供了额外的定制，可以减少臃肿。它看起来像：

GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

稀疏字段集是一种标准化方法，它允许客户端仅指定他们希望从对象中包含在响应中的属性。使用稀疏字段集，您只能获得所需的字段，提供独特的定制潜力，这对精益数据共享环境很有吸引力。

可选性

JSONAPI.org 中的许多功能都是可选的；您可以关闭或打开它们。这些功能使客户能够决定接受哪些资源，从而很好地适应精益的移动环境。让客户就如何检索和处理数据达成一致是有帮助的，因为它消除了冗余和优化以减少膨胀。

优化功能

JSON API 配备了许多功能来优化 API 返回包。JSON API 中的特殊服务器端操作包括排序和分页；将返回资源的数量限制为子集的能力，包括 first、last、next 和 prev 链接。

缓存

在他的演讲中，Lee 强调了定义良好的资源如何提高缓存能力，从而提高最终用户的“感知速度”。

“因为数据变化影响的资源更少，所以数据变化时失效的资源更少”

在 JSON API 用例中，缓存本质上是内置在 HTTP 中的。由于使用 JSON API 的客户端以相同的方式访问数据，因此他们不需要将数据存储在不同的位置。这种设计可能需要转变思想，但如果使用得当，可以带来显着的优化优势。

JSON API 如何在实践中使用：FitBit 案例研究

让我们看看 JSON API 如何在实践中实现以设计高效的 API，使用 FitBit 作为现实生活中的案例研究。

Jeremiah Lee 在 FitBit 领导 API 开发 4 年，在此期间他参与了他们的 JSON API 采用。健身可穿戴公司 FitBit 拥有蓬勃发展的 API 程序；在每年 40 亿次请求中，有 1/4 是通过第三方应用程序完成的，收入可观。

符合 API 风格有助于标准化客户端

一个常见的问题是当不同的客户端类型偏好不同的方法来从服务器检索数据时。围绕功能区域形成的工程团队通常一次一个平台地逐步实施新功能，并在每个客户端中找到相反的约束。

Lee 描述了 FitBit 团队如何拥有四个主要客户：Android、iOS、Windows 和 Web。一个主要问题是 Android 和 iOS 对 API 应该如何运行有非常不同的想法。iOS 更喜欢较少的网络请求和较大的 API 响应，而 Android 更喜欢更多的网络请求和较小的 API 响应。

为了将这些约束规范化为一致的数据模型，团队必须首先解决请求数量和请求大小之间的争论。FitBit 团队在具有敌对数据网络的移动环境中工作，无法依赖理想的客户端连接。

相信 HTTP/2、TLS 1.3 和改进的 LTE 网络的日益普及，FitBit 团队决定他们可以减少请求的开销、发出并发请求并减少安全延迟问题，同时相信更多弹性连接。这将导致他们采用更小的资源和许多轻量级的 HTTP 请求。