我应该使用 accept http header 还是更明确的 rest api 资源来定义客户端请求的数据格式？

Question

假设我有一个 API，例如：/api/v1//modify?txtUri={a-text-file-uri-goes-here}，它过滤和修改位于给定 URI 的给定文本文件，并且有效负载中的 returns 响应过滤后的文本文件基于一些内部业务规则。

起初我只想 return JSON 但我想允许不同的 return 格式。

是否更好（即最标准的方式）：

• 使用不同的资源：

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/json
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/xml returns
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here} 默认回退，returns json

• 添加另一个可选的查询字符串参数format:

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=json return json 格式
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=xml returns xml 格式
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}默认回退，returns returns json

• 设置Accept httpheader:https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Accept为我们想要获取的return格式，如果不设置则return一个406 http代码。

Answer 1

使用 Accept header 作为 REST API 是 HTTP，这就是 HTTP 的工作方式。这也是您 API 的用户所期望的。

如果您不想使用 accept header，绝对不要使用 QueryString - 您可以一键使用扩展名，例如/api/v1/modify.json?txtUri={a-text-file-uri-goes-here} Twitter 这样做，但我的偏好是接受 header.