如何在我的 JSON API 响应中指定特定字段的内容类型和内容传输编码？答案

【问题标题】：How to specify the content-type and the content-transfer-encoding of a specific field in my JSON API response?如何在我的 JSON API 响应中指定特定字段的内容类型和内容传输编码？
【发布时间】：2020-11-05 03:31:05
【问题描述】：

我正在开发一个 API，给定具有特定内容的请求正文，它会生成一个可以采用不同格式（例如 pdf、png 等）的文档。鉴于文档可以是二进制文件，该文件采用 base64 编码并放置在如下所示的 json 响应中：

{
   "document": "document base64-encoded"
}

回复可能包含其他字段，但它们与问题无关。

我的问题是：

指定字段document的内容类型（例如pdf）和内容编码（例如base64）的最佳方式是什么？

我想到了一些选择，但我想听听你的建议。

我的选择

使用标头参数Content-Type 和Content-Transfer-Encoding：我认为这个选项是错误的，因为这些参数适用于消息本身，在这种情况下是application/json，没有任何编码。
指定自定义参数（例如x-document-content-type 和x-document-content-tranfer-encoding。
在响应正文中包含此类元数据，如下所示：

{
   "document": {
      "content": "document base64-econded",
      "type": "pdf",
      "econding": "base64"
   }
}

感谢您的意见！

【问题讨论】：

标签： json api types header base64

【解决方案1】：

这里有 2 层通信，每层都有自己的合同/协议。您自己的 JSON API 协议，通过 HTTP 协议发送。您应该坚持 HTTP 标准以遵守该层的合同，并且由您定义 JSON 数据的合同。

上面提到的 HTTP 标头用于告诉用户代理/客户端随附的 HTTP 正文的 MIME 类型是什么。这必须是 application/JSON 以符合 HTTP 标准。如果您从这里开始，它将不再是有效的 HTTP 流量，并且配置良好的常规 HTTP 客户端将无法使用您的 API。

HTTP 消息中的 JSON 正文可以填充您认为 API 的使用者使用编码内容所必需的任何内容。您在这里定义自己的合同，因此这完全取决于您和您的 api 消费者的需求。

您是否使用其他内容编码作为 base64？如果是这样，那么您可以指定数据的编码。

你们提供多种不同的文件类型吗？然后添加编码数据的内容类型很有用。请注意，编码内容的标头可能已经包含有关文件内容类型的信息。

附：提供你命名的“类型”可能会更好，作为一个 mime 类型。这作为定义内容类型的已知标准更为常见。

【讨论】：