知识卡片
公开服务定义入口
消费者需要理解具体接口,却找不到它的服务定义文档时,服务应提供一致的发现入口。
按接口风格选择服务定义文档SDD:书中列举HTTP CRUD用OpenAPI、事件用AsyncAPI、RPC用Protobuf、GraphQL用SDL等。书中的完整对应关系是:
| 接口风格 | 定义格式举例 |
|---|---|
| HTTP CRUD | OpenAPI、WADL |
| 事件驱动 | AsyncAPI、CloudEvents |
| 远程过程 | Protocol buffers、XML-RPC、JSON-RPC |
| 远程数据查询 | GraphQL SDL、OData |
| 远程消息 | WSDL |
| 超媒体 | ALPS作为当时建议 |
SDD帮助理解具体接口并生成文档或客户端,不能替代共享语义词汇。
在响应头、正文、OPTIONS和服务元数据中用rel="service-desc"指向文档。支持多种接口风格时可发布多个链接并标注type;书中有些SDD媒体类型是作者自用约定,不能视作现今注册标准。
关联:[[区分词汇与模式文档]]。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
在整书笔记中的位置
原书出处 · 1 处
- 超媒体服务 · 查看原书依据
The best way to do this is to return a link to the SDD in HTTP responses either as a link header, within the response body, or both. RFC 8631 defines a link relation value of service-desc to use when identifying links that point to SDD documents. It is also a good idea to return a pointer to the SDD in a link header in response to an HTTP OPTIONS request.
参考来源
- 位置:《RESTful Web API Patterns and Practices Cookbook》第5章《Hypermedia Services》(来源项目book-sources:extracted/RESTful Web API Patterns and Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data (Mike Amundsen)/_epub-src/OEBPS/ch05.xhtml,配方5.9)
- 结论依据:原文按六种接口风格列举SDD格式,给出service-desc在头、正文、元数据和OPTIONS的发布位置。
- 原始内容:The best way to do this is to return a link to the SDD in HTTP responses either as a link header, within the response body, or both. RFC 8631 defines a link relation value of service-desc to use when identifying links that point to SDD documents. It is also a good idea to return a pointer to the SDD in a link header in response to an HTTP OPTIONS request.