20、RESTful API设计：原理、示例与实用建议

RESTful API设计：原理、示例与实用建议

1. 知名URI与API探索

服务器可提供超媒体链接列表，指向其托管的其他资源。提供Web主机元数据文档的服务器，应始终从 /.well-known/host-meta 或 /.well-known/host-meta.json 提供该文档。借助知名URI注册表，理论上客户端仅通过主机名就能探索和了解新的API。不过，知名URI通常与特定媒体类型相关联。目前，若不使用CoRE链接格式或Web主机元数据，就无法在知名URI上发布API，因为知名URI注册表中仅这两种格式对API有用。

2. “你输入，我们发布”示例

2.1 列出语义描述符

对“你输入，我们发布”网站进行分析，确定以下语义描述符：
- 主页
- 关于本网站的文本
- 消息列表
- 单个消息
- 消息ID
- 消息文本
- 消息发布日期

将这些描述符分组后，得到三种不同的表示形式：关于本网站的文本、消息列表和单个消息。这里决定将消息列表作为“主页”，而非单独设置一个仅链接到消息列表和“关于本网站”的主页。

2.2 绘制状态图

以网站上的链接为指导，用安全状态转换连接三种类型的资源，并创建一个不安全状态转换，对应网站上创建新消息的HTTP POST表单。

2.3 协调名称

为状态图中的安全状态转换命名时，选择IANA注册的名称： about 、 collection