超媒体API：HATEOAS及其应用 | API 101 专栏 | 支流科技

关键要点

可发现的API： 超媒体API在响应中使用嵌入链接（超媒体）来引导客户端，减少对硬编码端点和外部文档的依赖。
HATEOAS原则： 这一REST约束确保客户端仅通过服务器提供的超媒体与应用交互。
好处： 主要优势包括增强的API自描述能力、减少客户端-服务器耦合、改进一致性以及更高的可演进性，使API更易于维护。
实现： 采用HAL或JSON:API等标准，并通过包含导航和操作链接设计可发现性至关重要。
API网关角色： 网关可以帮助强制执行超媒体标准、动态生成链接并增强超媒体驱动操作的安全性。

简介

在现代软件架构的复杂织锦中，构建不仅功能完善而且适应性强和可发现的API至关重要。RESTful API设计原则已经显著演进，超越了简单的数据检索，采用更动态和智能的交互模型。这一演进的前沿是超媒体API和被称为**HATEOAS（超媒体作为应用状态引擎）**的指导原则。

由HTTP规范的基础人物Roy Fielding创造，HATEOAS代表了REST架构风格的核心约束。它倡导API通过在响应中嵌入链接和上下文数据来内在地引导客户端完成可用操作和资源，而不是强迫客户端依赖外部的、经常脆弱的文档。

本文将深入探讨超媒体API和HATEOAS的本质，探索它们深远的益处，并展示它们为开发人员和API架构师构建更具弹性和面向未来系统的实际应用。

什么是超媒体API和HATEOAS？

超媒体API的核心概念很简单：它是一个RESTful API，在响应中使用超媒体——想想链接、表单和其他交互控件——来引导客户端下一步可以执行什么操作。这种方法深深植根于**HATEOAS（超媒体作为应用状态引擎）**原则，这是REST架构风格的基本约束。Roy Fielding是HTTP规范的主要作者之一，他强调，为了使API真正具有RESTful特性，客户端必须能够仅通过响应中提供的超媒体与应用交互。

这意味着，客户端开发人员不需要记住特定操作的不同API端点，也不需要查阅大量外部文档来理解如何从一个状态转换到另一个状态，API本身就提供了这种指导。当客户端请求资源时，服务器的响应不仅包含数据，还包含指示可能下一步的链接。例如，如果客户端检索订单，响应可能包含指向"跟踪发货"或"取消订单"的链接，以及必要的URI，甚至可能还有如何执行这些操作的模式信息。这种动态发现机制减少了客户端硬编码API路径的需要，培养了更灵活、更不脆弱的客户端-服务器关系。API通过其超媒体控件变得自文档化和自解释。

1sequenceDiagram
2    participant Client
3    participant Server
4
5    Client->>Server: GET /orders/123
6    Server-->>Client: 200 OK - 订单详情及_links (self, cancel_order, customer)
7    Client->>Client: 解析响应，找到'cancel_order'链接
8    Client->>Server: POST /orders/123/cancel (使用响应中的链接)
9    Server-->>Client: 200 OK - 订单已取消，包含更新状态的_links

为什么要拥抱超媒体API和HATEOAS？

采用HATEOAS和超媒体进行API设计不仅仅是一个学术练习；它提供了切实的、显著的优势，直接有助于软件系统的长寿性、可维护性和整体健壮性。通过将关于可用操作和状态转换的智能嵌入API响应中，HATEOAS促进了更松散耦合的架构，其中服务器决定应用流程，而不是客户端需要预先知道所有信息。

让我们探索为什么拥抱这种架构风格是有益的：

自描述API和增强的可发现性： 这也许是最显著的好处。在符合HATEOAS的API中，客户端不需要负担记住或发现每个端点的任务。当客户端请求资源时，响应本身包含超链接，清晰指示相关资源和可用操作。例如，GET /orders/123的响应可能链接到/orders/123/items、/customers/456，以及诸如/orders/123/cancel或/orders/123/pay之类的操作。这使得API本质上更容易理解和使用，降低了开发人员集成系统的学习曲线。这就像浏览一个网站，每个页面都有指向相关内容和其他操作的链接，而不是每次交互都需要站点地图和手册。有效利用这些原则的公司可以看到客户端API集成复杂性降低高达40%，根据行业分析。
减少客户端-服务器耦合和增加可演进性： HATEOAS促进的松散耦合对于长期可维护性至关重要。如果服务器端URI结构更改，或引入新操作，遵守超媒体控件的客户端不一定会破坏。只要服务器在其响应中提供更新的链接，客户端就可以动态适应。想象一下，公司想要将取消订单的URI从/orders/{id}/cancel更改为/order-management/v2/orders/{id}/initiate-cancellation的场景。如果客户端使用HATEOAS响应中提供的rel="cancel_order"链接，它将简单地遵循服务器提供的新URI，而无需任何代码更改。在快节奏的开发环境中，这种敏捷性是无价的。
改进接口设计的一致性和统一性： HATEOAS促进了与资源交互的统一接口，特别是对于状态转换和操作。通过标准化操作表示方式（例如，始终使用具有特定rel属性的链接表示特定操作），API变得更加可预测和直观。这种一致性减少了客户端开发人员的歧义，使API感觉更加内聚。例如，所有"更新"操作可能始终使用rel="edit"的链接并指定适当的HTTP方法（例如PUT或PATCH）。
面向未来的API投资： 通过将客户端与特定URI结构解耦并使API可发现，HATEOAS作为面向未来的自然形式。随着应用演进和重构后端系统，只要服务器端正确管理超媒体链接，从客户端角度看API保持稳定。这降低了持续维护成本以及与API更改相关的风险，使企业能够更有信心地创新。Fielding本人强调了这一点，他说："REST API应该仅用初始URI就可以进入……其余的交互由超文本驱动。"

本质上，采用HATEOAS将控制和知识重心转移到服务器，使API更加智能、自描述和抗变化。这导致更健壮的应用、新功能的更快开发周期，以及随着时间推移客户端开发人员的显著减少的负担。

实现超媒体API：概念和最佳实践

成功实现符合HATEOAS的API涉及对设计的深思熟虑的方法，利用既定的超媒体标准，并了解如何有效地在API响应中嵌入上下文信息。它需要将API作为自己的指南的心态转变。

要理解的核心概念：

链接至关重要： 超媒体的基础是链接。在RESTful上下文中，链接通常表示为一组键值对，最重要的是包含：
- href：资源或操作的统一资源标识符（URI）。
- rel：描述链接用途或性质的关系术语。这对可发现性至关重要。示例：self、next、previous、edit、delete、view_details。
- 其他属性可以包括method（例如GET、POST、PUT）、type（资源的媒体类型）、title（人类可读的描述）和hreflang（链接资源的语言）。
表示简单导航之外的操作： HATEOAS不仅仅是链接到现有资源；它还涉及暴露可以对这些资源执行的操作或响应其当前状态。这些操作由具有描述性rel值的链接表示。对于状态改变操作，链接可能还包括HTTP方法，以及可能指示预期请求负载格式的type。
嵌入相关资源： 为了减少客户端需要进行的往返次数，超媒体标准通常允许在主资源响应中直接嵌入相关资源。例如，订单资源可以嵌入其关联的行项目。这通常在响应中的专用_embedded或embedded部分完成。然而，这必须与潜在的负载大小增加相平衡。

利用超媒体标准实现结构和互操作性：

虽然你可以发明自己的超媒体结构，但使用既定标准显著改善了不同客户端和服务器之间的互操作性。

HAL（超文本应用语言）(application/vnd.hyper+json)： HAL是一种简单、广泛采用的约定，用于在JSON中创建表示链接和嵌入资源的结构化方式。它通常使用：
- _links：包含所有链接的对象，由rel属性键入。
- _embedded：包含嵌入资源的对象，由表示关系的名称键入。
- HAL链接示例："self": { "href": "/orders/123" }
- HAL操作示例："cancel_order": { "href": "/orders/123/cancel", "method": "POST" }
这篇博客讨论了Spring HATEOAS通常如何将链接序列化为嵌套在_links键下的JSON对象，每个链接由其关系（rel）表示。
JSON:API (application/vnd.api+json)： JSON:API是一种更有主见的规范，定义了构建JSON API的严格规则集，包括如何表示资源、关系、属性和链接。它提供了一种高度结构化和一致的方式来构建超媒体API。它强调：
- links：包含资源本身、相关资源和分页的链接。
- data：主资源对象。
- attributes：资源属性。
- relationships：指向相关资源的链接。
- JSON:API链接示例："links": { "self": "/articles/1" }
Collection+JSON (application/vnd.collection+json)： 该标准专门设计用于表示资源集合，并包含与集合本身（例如分页）和集合内项目相关的链接机制。

设计和实现的最佳实践：

从一开始就设计可发现性： 在设计API资源时，考虑整个生命周期和潜在交互。对于每个资源表示，问自己：客户端现在可以对这个资源做什么？有哪些其他资源直接相关？
- self链接： 始终包含指向资源URI的self链接。
- 集合导航链接： 对于集合端点（例如/orders），包含分页链接：next、prev、first、last。
- 操作链接： 对于与工作流绑定的资源，包含表示有效状态转换的链接。如果订单可以支付、发票已付、已发货或已取消，为这些操作提供不同的链接，可能具有描述性的rel值如pay_invoice、track_shipment、cancel_order。为这些操作链接包含适当的HTTP方法。
- 相关资源链接： 如果资源与另一个相关（例如订单与客户），提供指向该相关资源的链接，使用描述性rel如customer或customer_details。
- 嵌入策略： 对于紧耦合或频繁访问的相关数据（如订单响应中的订单行项目），考虑嵌入它们以减少客户端往返。注意负载大小，只嵌入通常需要一起的内容。
使用清晰、有意义和标准化的rel属性： rel属性是超媒体链接的语义核心；它告诉客户端链接的用途。
- 标准关系： 对于常见模式如导航（next、prev）或资源类型（customer、product），在适当的地方使用已建立的链接关系类型（例如来自IANA的链接关系类型注册表）。
- 自定义操作关系： 对于应用特定的操作，定义清晰、描述性的自定义rel值。避免神秘的缩写。不要用rel="p"，而用rel="pay_invoice"。不要用rel="edit"，也许用rel="update_profile"如果更具体。
- 命名空间自定义关系： 为了避免与标准关系类型冲突，特别是如果构建大型、复杂的API，考虑命名空间自定义关系（例如my-api:add-to-cart）。

一致地构建响应： 无论你选择HAL、JSON:API还是自定义结构，都要确保所有API端点的一致性。结构良好的响应使客户端更容易解析和利用超媒体。

以下是一个演示带有嵌入行项目和操作链接的订单的HAL式结构的示例：

1{
2  "id": "ORD-789",
3  "order_date": "2023-10-27T10:00:00Z",
4  "total_amount": 150.75,
5  "status": "处理中",
6  "_links": {
7    "self": { "href": "/orders/ORD-789" },
8    "customer": { "href": "/customers/CUST-456" },
9    "invoice": { "href": "/invoices/INV-101" },
10    "cancel_order": {
11      "href": "/orders/ORD-789/cancel",
12      "method": "POST",
13      "title": "取消此订单"
14    },
15    "update_shipping": {
16      "href": "/orders/ORD-789/shipping",
17      "method": "PUT",
18      "title": "更新发货详情"
19    }
20  },
21  "_embedded": {
22    "order_items": [
23      {
24        "id": "ITEM-001",
25        "product_id": "PROD-ABC",
26        "quantity": 2,
27        "item_price": 50.00,
28        "_links": {
29          "self": { "href": "/orders/ORD-789/items/ITEM-001" },
30          "product": { "href": "/products/PROD-ABC" }
31        }
32      },
33      {
34        "id": "ITEM-002",
35        "product_id": "PROD-XYZ",
36        "quantity": 1,
37        "item_price": 50.75,
38        "_links": {
39          "self": { "href": "/orders/ORD-789/items/ITEM-002" },
40          "product": { "href": "/products/PROD-XYZ" }
41        }
42      }
43    ]
44  }
45}

为操作考虑类型和模式： 对于表示需要输入的操作的链接（如更新发货详情或添加到购物车），你可以包含method和type属性。对于更复杂的输入，你甚至可以包含schema或templatedURL来描述所需参数，类似于OpenAPI（Swagger）的工作方式。
构建通用客户端或利用库： 要真正从HATEOAS中受益，请构建能够感知超媒体的客户端应用。客户端解析响应，根据rel属性（例如查找rel="cancel_order"的链接）找到链接，然后使用提供的href和method进行后续请求。许多编程语言都有库可以帮助解析HAL或JSON:API响应并管理超媒体导航。

超媒体API和HATEOAS的应用

HATEOAS和超媒体的原则在需要灵活性、演进接口的场景中特别强大，并且减少了需要理解复杂、有状态工作流的客户端开发人员的负担。

内容管理系统（CMS）和后端： 在CMS中，管理文章、页面、用户资料或媒体项目涉及各种状态和可能的操作。符合HATEOAS的API可以直接在资源响应中暴露链接，用于诸如"编辑"、"发布"、"取消发布"、"删除"或"查看分析"之类的操作。对于内容编辑者来说，这意味着他们可以从API响应中看到对于给定内容在任何时间允许哪些操作，使编辑界面动态并响应内容状态。
电子商务平台： 电子商务中的客户旅程为HATEOAS提供了丰富的应用场景。考虑客户下达的订单：
- 初始订单响应可能包括诸如self（用于订单详情）、customer（用于查看客户信息）、invoice（用于下载发票）之类的链接，以及潜在的操作如cancel_order（如果在取消窗口内）。
- 如果订单状态更改为"已发货"，链接可能会更新以包括track_shipment（带有指向承运商跟踪页面或内部跟踪服务的URI）并删除cancel_order链接。
- 对于产品列表，链接可以是add_to_cart、add_to_wishlist、view_details和compare_product。这允许电子商务前端基于当前状态和可用操作动态渲染按钮和链接，而不是依赖每个可能场景的硬编码逻辑。
工作流和状态机管理： 许多业务流程涉及不同的状态和转换（例如订单履行、贷款申请处理、用户入职）。HATEOAS自然地建模这些工作流。表示特定状态资源的每个API响应可以提供指向下一个有效转换的链接。
- 例如，"草稿"状态中的应用可能链接到/applications/{id}/submit或edit_application。一旦"已提交"，它可能链接到/applications/{id}/status或view_status。这使工作流流程可通过API本身发现和可管理。
资源集合和动态分页： 处理大量数据集合时，HATEOAS为分页提供了优雅的解决方案。返回/products集合的响应可能包括next、prev、first和last链接，指示获取其他结果页面的URI。这消除了客户端计算页码或偏移量的需要，使分页逻辑可重用和健壮。
通用API客户端和工具： HATEOAS的原则有助于构建通用API客户端或工具。可以构建一个应用来消费任何符合HATEOAS的API。这样的客户端将解析链接，理解其rel属性，并呈现与不同后端服务交互的一致界面，大幅减少API特定客户端开发的需要。这一概念类似于Web浏览器如何使用超链接导航互联网。
遗留系统现代化（API外观）： 对于拥有现有遗留系统的组织，通过现代超媒体API暴露其功能可以是一种渐进现代化的策略。API外观可以将遗留操作转换为HATEOAS驱动的交互，使底层系统更可发现和适应，而无需完全重写。

超媒体采用的挑战和注意事项

虽然HATEOAS的优势是显著的，但其采用并非没有挑战。务实的方法需要理解这些障碍：

增加的负载大小： 在每次API响应中嵌入详细链接、关系和可能的模式自然会增加负载大小，相比仅返回数据的极简API。对于每字节都很重要的API（例如低带宽移动环境），这种增加的负载需要仔细管理。使用高效标准（例如HAL而非过于冗长的自定义结构）和谨慎使用嵌入资源等策略是关键。
客户端开发复杂性和初始投资： 构建真正感知超媒体的客户端应用需要以不同的方式思考API交互。开发人员必须学习解析超媒体控件并动态确定下一步，而不是依赖硬编码URI。虽然这项投资在长远来看通过减少维护得到回报，但初始学习曲线和开发工作可能更高。
开发人员教育和认同： HATEOAS是许多开发人员可能不熟悉的模式。有效传达其好处并提供培训或清晰的示例对于获得团队认同并确保跨服务的一致实施至关重要。
工具支持和框架支持成熟度： 虽然像HAL和JSON:API这样的标准定义明确，但支持生成、解析和利用超媒体的库、框架和工具的生态系统在不同编程语言和平台之间的成熟度可能不同。确保你选择的堆栈具有足够的超媒体支持至关重要。
何时它是过度的？ 对于非常简单、静态的API，具有可预测的交互（例如固定的一组只读端点），实施完整HATEOAS的开销可能超过好处。在这种情况下，更直接的RPC式URI结构可能更简单和更合适。采用HATEOAS的决定应由特定应用域预期的复杂性、可演进性需求和可发现性愿望驱动。

API网关如何融入超媒体图景

虽然HATEOAS从根本上说是在API负载级别的客户端-服务器交互设计模式，但API网关可以在促进其实施和增强消费超媒体API的体验方面发挥重要作用。

此图显示了API网关如何简单地将请求和响应路由，而不改变超媒体链接，让客户端完全通过HATEOAS驱动流程。

1sequenceDiagram
2    Client->>Gateway: GET /orders/123
3    Gateway->>Orders: 转发
4    Orders-->>Gateway: 200 + HAL链接
5    Gateway-->>Client: 200 + HAL (未修改)
6    Client->>Gateway: 跟随链接 → /payments/123
7    Gateway->>Payments: 转发
8    Payments-->>Gateway: 200 + 下一个链接
9    Gateway-->>Client: 200 + HAL (未修改)

强制执行超媒体标准和一致性： API网关可以配置为验证来自后端服务的响应是否遵守指定的超媒体标准（例如期望HAL或JSON:API结构）。这充当质量控制机制，确保为API外观做出贡献的所有服务保持一致的超级媒体接口。这在多个团队可能开发不同服务的微服务架构中特别有用。
动态链接生成和增强： 对于常见的超媒体元素如self链接或分页链接（next、prev），API网关有时可以配置为动态地将这些注入响应。这可以将一些超媒体生成负担从各个后端服务中卸载，特别是在包装可能本机不支持HATEOAS的遗留微服务时。网关可以根据传入请求和后端响应构造这些链接，确保一致性。
促进通用API客户端： 通过充当暴露良好定义的超媒体API外观的统一网关，客户端开发人员更容易构建通用客户端。客户端可以与网关交互，然后智能地将请求路由到适当的后端服务，同时保持超媒体契约。这种抽象增强了客户端的长寿性。
安全和操作执行： 如果特定的超媒体链接表示关键操作（例如cancel_order或process_payment），API网关可以配置为为这些URI模式专门强制执行安全策略（认证、授权、速率限制），为状态改变操作添加额外的控制和安全性。例如，通过网关暴露的/cancel_order的POST请求可能会被阻止，如果发出请求的用户未经授权，或者如果已达到取消的速率限制。

以下是显示API网关如何与超媒体配合工作的图示：

1sequenceDiagram
2    participant Client
3    participant API_Gateway
4    participant Backend_Service_A
5    participant Backend_Service_B
6
7    Client->>API_Gateway: GET /orders/123
8    API_Gateway->>Backend_Service_A: 转发订单123的请求
9    Backend_Service_A-->>API_Gateway: 订单数据及HAL链接 (self, cancel, customer)
10    API_Gateway->>API_Gateway: 用集合的'next'链接增强响应
11    API_Gateway->>API_Gateway: 对'cancel'操作链接强制执行安全
12    API_Gateway-->>Client: 200 OK - 包含增强HAL链接的订单数据
13
14    Client->>API_Gateway: POST /orders/123/cancel (使用响应中的链接)
15    API_Gateway->>Backend_Service_A: 转发取消POST请求
16    Backend_Service_A-->>API_Gateway: 200 OK - 订单已取消，状态已更新
17    API_Gateway-->>Client: 200 OK - 成功消息及更新链接

这展示了网关如何充当智能中介，增强超媒体体验并确保持续应用策略。

结语：用超媒体API构建可演进和可发现的系统

超媒体API在HATEOAS健壮原则的指导下，提供了一种成熟而复杂的RESTful API设计方法，显著增强了可发现性、可维护性和可演进性。通过在API响应中直接嵌入上下文链接和可操作控件，HATEOAS驱动的API使客户端能够动态导航应用状态并发现可用操作，从而减少对硬编码URI和外部文档的依赖。这导致更具弹性、适应性和可维护性的系统，能够更好地承受后端架构不可避免的变化。

虽然存在诸如增加负载大小和初始客户端开发投资等挑战，但减少耦合、改进API一致性和固有面向未来的长期益处往往超过这些考虑，特别是对于复杂或演进的应用。采用HAL或JSON:API等既定超媒体标准并专注于清晰、描述性的关系术语是最大化这些好处的关键。此外，**API网关**可以通过强制执行标准、动态增强具有常见超媒体元素的响应以及保护状态改变操作，在促进HATEOAS采用方面发挥关键作用。

对于致力于构建高质量、适应性强的软件解决方案的开发人员和组织来说，理解并实施超媒体原则不仅仅是最佳实践，而是战略优势。它培养了更智能、状态驱动的交互模型，真正体现了RESTful愿景，将API转变为可发现的数字业务引擎。通过拥抱HATEOAS，你正在投资API生态系统的未来适应性和可维护性。