内容谈判

内容协商是指一个 URL 可以呈现多种不同的内容形式。客户端声明它能接受的内容；服务器从它能生成的资源中选择；响应会告知最终选择了哪种。资源本身是相同的，只是呈现方式不同。

工作原理

客户端发送 Accept 请求，并指定所需的媒体类型，还可以选择使用 q 值进行加权。服务器回复 Content-Type，指明实际发送的内容，并且应该发送 Vary: Accept，以防止缓存将 JSON 响应返回给请求 CSV 格式的客户端。如果服务器无法提供客户端可接受的媒体类型，则返回 406 Not Acceptable 错误。反之，如果客户端发送的请求体类型服务器无法解析，则返回 415 Unsupported Media Type 错误。

误解

Accept 请求头只是建议性的，可以忽略。许多 API 确实会忽略它，始终返回 JSON 数据，这在客户端真正需要其他数据时不会造成问题，此时 API 会静默地返回 JSON 数据和 200 状态码。对于无法满足的 Accept 请求头，正确的响应是返回 406 状态码。

点击这里试试

Protocol Lab 会进行真正的协商： `GET /protocol/v1/export/documents`会根据你的 Accept 请求头生成 JSON、CSV 或 XML 文件，并将 Content-Type 设置为它选择的值，并在请求无法处理时返回 406 错误，而不是默默地回退。而 Friends API 则会在请求传入时返回 415 错误。

相关内容

• HTTP 406 Not Acceptable
• HTTP 415 Unsupported Media Type

资料来源

• HTTP semantics — RFC 9110
• HTTP caching — RFC 9111

其他术语

• REST API — 将系统建模为可寻址资源的 API，可通过标准 HTTP 方法进行操作。
• API 端点 — 一个 URL 加上一个 HTTP 方法——客户端可以调用的最小 API 单元。
• 查询参数 — URL 中问号后面的键值对，用于过滤、排序、分页或调整端点返回的内容。
• 路径参数 — URL 路径中的可变部分，例如/orders/42中的 42，用于标识一个特定的资源。
• HTTP 标头 — 每个请求和响应都会发送名称-值元数据，与请求体分开。
• HTTP 状态码 — 每个 HTTP 响应开头的三位数，在响应体之前，表示发生了什么。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日