API客户端开发：语义、格式与模式的处理策略

# API 客户端开发中的词汇表、格式与模式处理 ## 1. API 服务与词汇表 在 API 开发中，服务通常会发布 API 定义文档，如 OpenAPI、AsyncAPI、RAML 等。这些文档对想要实现单个 API 服务实例的人很有用，但对 API 消费者的价值有限。当 API 客户端应用程序使用服务实现规范来创建 API 消费者时，该应用程序将与特定的服务实现紧密绑定。服务实现的任何更改都可能导致客户端应用程序出现故障。 更好的方法是将 API 消费者绑定到已发布的配置文件文档上。如果所使用的服务没有发布稳定的词汇表文档，那么创建自己的文档是个不错的选择。可以使用 API 定义文档（如 OpenAPI）作为指导，创建自己的 ALPS 文档（或其他所需格式的文档），并将其发布供团队（和其他人）在为该服务创建 API 客户端时使用。同时，将该 ALPS 文档包含在客户端应用程序的源代码仓库中，以便日后参考。 当所使用的服务返回超媒体响应时，词汇表配置文件能发挥最大的作用。如果服务不返回超媒体响应，且无法影响服务团队，可以按照响应中包含超媒体的方式来编写客户端代码。 ### 1.1 词汇表处理步骤 - **检查服务是否有稳定词汇表文档**：若没有，则自行创建。 - **依据 API 定义文档创建自定义文档**：如 ALPS 文档。 - **发布自定义文档**：供团队和其他开发者使用。 - **将文档纳入客户端代码仓库**：方便后续参考。 ## 2. 运行时语义配置文件支持的协商 ### 2.1 问题提出 客户端应用程序依赖使用预定语义配置文件提供响应的服务时，需要确认服务是否使用了所需的词汇表。例如，客户端代码已编写为可与符合 ToDo 语义配置文件的任何服务协作，那么如何在运行时确认即将使用的服务是否支持待办事项词汇表呢？ ### 2.2 解决方案 客户端应用程序可以使用“配置文件协商”模式可靠地检查服务对语义配置文件的支持情况。客户端可以使用 `accept-profile` 请求头来指示预期的语义配置文件，而服务可以使用 `content-profile` 响应头来指示支持的语义配置文件。 与内容协商类似，配置文件协商允许客户端和服务器共享有关资源表示的元数据详细信息，并决定服务器的响应是否可被客户端接受。当服务返回的资源配置文件与客户端的请求不匹配时，客户端可以报错拒绝响应、向服务器请求更多信息或继续处理。 ### 2.3 示例 以下是一个简单的配置文件协商示例： ```plaintext *** REQUEST GET /todo/list HTTP/1.1 Host: api.example.org Accept-Profile: <http://profiles.example.org/to-do> *** RESPONSE HTTP/2.0 200 OK Content-Profile: http://profiles/example.org/to-do ... ``` 在这个示例中，客户端使用 `accept-profile` 头指示所需的词汇表，服务使用 `content-profile` 头告知客户端用于构建返回资源表示的配置文件。 当客户端请求服务不支持的语义配置文件时，服务器可能会返回 406 HTTP 状态码（不可接受）。此时，服务应返回指示该服务准备支持哪些配置文件的元数据： ```plaintext *** REQUEST GET /todo/list HTTP/1.1 Host: api.example.org Accept-Profile: <http://profiles.example.org/to-do/v3> *** RESPONSE HTTP/2.0 406 Not Acceptable Content-Type: application/vnd.collection+json { "collection": { "links" : [ {"rel":"profile", "href":"http://profiles.example.org/todo/v1"}, {"rel":"profile", "href":"http://profiles.example.org/todo/v2"}, ] }, "error" : { "title" : "Unsupported Profile", "message" : "See links for supported profiles for this resource." } } ``` 服务还可以提供一种方式，让客户端应用程序预先请求支持的语义配置文件的详细信息。服务可以提供一个或多个关系值为“profile”的链接，每个链接指向一个支持的语义配置文件文档。例如： ```json { "collection": { "title" : "Supported Semantic Profiles", "links" : [ {"rel":"profile", "href":"http://profiles.example.org/todo/v1"}, {"rel":"profile", "href":"http://profiles.example.org/todo/v2"}, {"rel":"profile", "href":"http://profiles.example.org/todo/v3"} ] } } ``` ### 2.4 协商流程 ```mermaid graph LR A[客户端发送请求] --> B{服务是否支持请求的配置文件} B -- 是 --> C[服务返回 200 OK 并携带 content-profile 头] B -- 否 --> D[服务返回 406 Not Acceptable 并提供支持的配置文件信息] ``` ### 2.5 讨论 对于“按配置文件编写代码”的客户端应用程序，验证所有传入响应以确保能够正确处理资源是个好做法。由于服务器实际上可能在响应中报告多个配置文件链接，客户端应用程序应假设所有配置文件元数据都作为集合报告，并在该集合中搜索所需的配置文件标识符。 使用 `accept-profile` 和 `content-profile` 进行语义配置文件协商并不常见。相关规范仍为草案文档，截至目前，W3C 关于配置文件的最新工作仍在进行中。然而，在封闭系统（如企业 IT）中，实现配置文件协商可以是一种促进和鼓励普遍使用语义配置文件的好方法。 不建议过于详细地标识语义配置文件版本（如 v1、v1.1、v1.1.1 等），因为这会增加客户端应用程序和远程服务在运行时的工作量。当需要对配置文件进行更改时，应尽可能保持更改向后兼容。如果配置文件更新导致了重大更改，应更新标识符以指示新版本（如 v1 → v2）。 ## 3. 运行时管理表示格式 ### 3.1 问题提出 需要与多个服务进行交互的客户端应用程序可能需要以多种消息格式（如 HTML、HAL、SIREN、Collection+JSON 等）进行“通信”，这意味着需要在运行时识别和处理多种消息格式。那么，需要处理多种消息类型的客户端应用程序如何请求和验证从服务接收的消息类型，并