15、超媒体 API 设计：格式与语义挑战

超媒体 API 设计：格式与语义挑战

1. API 规范与超媒体替代方案

在 API 设计中，“flip” 这个操作可能出现在开关内的表单提交控件上，激活该控件会翻转开关状态。这便是一个 API 的规范示例，类似于 Maze+XML 这样的个人标准。不过，仍有一些未明确的问题：
- HTML 文档样式 ：无需严格定义 HTML 文档的具体样子。hMaze 实现既可以提供包含大量说明文本、供人类阅读的完整文档，也可以提供为自动化客户端优化的紧凑文档。只要正确使用 hMaze CSS 类和链接关系，对文档样式的选择不会影响迷宫应用的语义。
- 神秘开关资源 ：神秘开关是否可以作为具有自身表示形式的一等资源？示例中的开关有自己的 URL（/switches/4），但客户端只能对其发送 POST 请求，不能发送 GET 请求。虽然可以想象一个指向该 URL 的链接，如 <a rel="switch" href="/switches/4">mysterious switch</a> ，但由于未定义 “switch” 链接关系，这不属于当前设计。

如今常见的 API 文档会将大量服务器端方法作为离散的 API 调用公开，为每个调用指定单独的操作 URL 并详细记录。例如，要翻转开关，需向 http://api.example.com/switches/{id}?action=flip 发送 POST 请求，其中 {id} 是开关 ID，且只有与开关处于同一单元格时才能翻转开关。这种做法是用人类可读的文档替