使用自定义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，当然。