使用自定义 json 内容类型是个好主意吗

Question

我正在设计一个 RESTful API，并试图进行描述并使文档更清晰，我想如下声明我的内容类型 http 标头：

Content-Type: application/vnd.mycorp.mydatatype+json

其中 mycorp 是我的公司唯一的标识符，而 mydatatype 对每种数据类型都是唯一的。一个例子是：

Content-Type: application/vnd.ford.car+json

{
"manufactured_year": 2000
, "color": "blue"
, "hp": 160
, "model" "Focus"
, "type": "sedan"
}

需要此内容类型才能使 POST 有效，并将作为响应的一部分发送。在我看来，这似乎是一种很好的方式来定义有效载荷中应该包含的内容的规则。

我似乎找不到关于这是否是一个好主意或者它是否被 IETF 标准允许的好资源。

那么，问题是：哪个更可行，application/vnd.mycorp.mydatatype+json 还是只是 application/json？

Answer 1

该问题与您的 REST API 版本控制密切相关。

内容类型用于定义内容的类型。 如果您使用 标准 内容类型，例如

application/json

您是在告诉客户端消息是 JSON 格式的。这对于所有不对其 API 进行版本控制或仅支持最新版本的 Web 应用程序来说已经足够了。 如果您要让客户端使用不同版本的 API，标准 内容类型是不够的。 考虑以下场景：

以你的例子作为消息的版本 1

Content-Type: application/vnd.ford.carV1+json

{
"manufactured_year": 2000
, "color": "blue"
, "hp": 160
, "model" "Focus"
, "type": "sedan"
}

在某些时候，您决定要使用十六进制代码表示颜色。因此，您创建类型的第 2 版

Content-Type: application/vnd.ford.carV2+json

{
"manufactured_year": 2000
, "color": "0000FF"
, "hp": 160
, "model" "Focus"
, "type": "sedan"
}

当客户要求汽车时，请指定正确的内容类型，其中包括版本。这告诉应用程序是以十六进制代码还是名称发送颜色。

在这里，您正在对资源的表示进行版本控制。支持资源表示版本控制的另一种方法是将版本添加为自定义标头（同时保持内容类型标准）

Content-Type: application/json
Message-Version: 1.0

Answer 2

绝对是允许的。这是否是一个好主意是另一回事。

我的经验法则是，它是一种主要的数据格式，在很多方面都很有用，需要自行识别，并且您需要在许多应用程序之间进行互操作，一定要给它一个媒体类型。

但是，如果它只是您的 API 中的一条消息，并且它只对一种资源（或一种资源“类型”）有用，则只需使用 application/json。

YMMV，当然。