知识卡片

问题卡 · 3481.h.2

公开服务定义入口

理解等级:中级

消费者需要理解具体接口,却找不到它的服务定义文档时,服务应提供一致的发现入口。

按接口风格选择服务定义文档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媒体类型是作者自用约定,不能视作现今注册标准。

关联:[[区分词汇与模式文档]]。

这张卡片看不懂?

已有反馈 · 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.