22、超媒体 API 设计与应用指南

超媒体 API 设计与应用指南

1. 超媒体的重要性及问题

在 API 开发中，部署新的服务器软件时，我们需要确保不破坏已部署的客户端。改变 API 所需的时间取决于用户基数和社区适应变化的平均速度，例如改变银行 API 会耗时很久，而改变微博 API 则相对较快。

超媒体在这个过程中至关重要。将更多的协议和应用语义以机器可读的形式呈现，就能在不经历缓慢繁琐流程的情况下更改 API。

过去非 RESTful API 的典型特征是服务描述文档，通常是 WSDL 格式的大文档，完整描述了 API 的协议和应用语义。用户可下载该文档自动生成对应的客户端实现，像进行本地编程语言调用一样进行远程 API 调用，无需了解超媒体、表示格式或 HTTP。然而，一旦服务器端实现发生变化，整个系统就会崩溃。

这是因为这种设计在 API 的服务器端实现、机器可读描述和基于该描述生成的客户端之间建立了紧密耦合。服务器端实现改变时，生成的客户端无法反映这些变化，导致客户端崩溃。

传统的 API 文档实际上是人类可读的服务描述文档，虽然比 WSDL 文件更易理解，但也存在同样的问题。服务器端实现的改变会导致“服务文档”改变，但已部署的客户端无法得知这些变化，从而导致客户端崩溃。

基于超媒体的 API 有一定能力在不破坏客户端的情况下表达服务器端的变化，但这并非自动实现，需要付出努力。例如，用 HTML 编写机器可读的“服务描述文档”（即网站地图），虽然可以基于此自动生成 API 客户端，但服务器端实现变化时，客户端会因使用的是过时地图而崩溃。

因此，超媒体 API 的客户端不能提前知晓所有可能的状态转换，应设计得像迷宫求解器，能