16、API 文档中的配置文件：概念、作用与使用方法

API 文档中的配置文件：概念、作用与使用方法

1. API 设计规则概述

在 API 设计过程中，有一系列规则可供遵循：
- 若存在针对问题的特定领域标准，使用该标准，并记录任何特定于应用程序的扩展。
- 若问题符合集合模式，采用其中一种集合标准，定义特定于应用程序的词汇表并记录。
- 若上述情况都不适用，选择通用的超媒体格式，将应用程序分解为状态转换并记录。
- 确定协议语义后，考虑是否有现有的微数据项或微格式适用于问题领域，若有则使用，否则定义特定于应用程序的词汇表并记录。

不同的超媒体格式适用于不同的应用场景，例如：
| 超媒体格式 | 适用场景 |
| ---- | ---- |
| HAL | 只读应用程序 |
| Maze+XML | 迷宫游戏类的只读应用程序 |
| AtomPub | 类似博客的读写应用程序 |

2. 客户端如何查找文档

在考虑 API 文档的形式之前，需要思考客户端如何找到文档。Fielding 约束之一是“自描述消息”，即服务器和客户端都不应猜测消息的含义。HTTP 的 Content - Type 头就是一个明显的例子，它告知如何解析实体主体，例如：
- Content - Type: text/html
- Content - Type: application/json
- Content - Type: application/atom+xml
- Content - Type: application/vnd.collection+json
- Content - Typ