Является ли использование пользовательских типов контента json хорошей идеей

Я разрабатываю 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?

Ответ 1

Это позволило, определенно. Хорошая идея - это еще одна история.

Мое эмпирическое правило состоит в том, что он является основным форматом данных, который полезен во многих вещах, должен быть идентифицирован сам по себе, и вам необходимо взаимодействовать во многих приложениях, определенно предоставляя ему тип медиа.

Однако, если это просто сообщение в вашем API среди многих, и оно полезно только для одного ресурса (или одного типа ресурса), просто используйте application/json.

YMMV, конечно.

Ответ 2

Вопрос сильно связан с вашим управлением версиями REST API.

Тип контента используется, чтобы определить тип содержимого. Если вы используете стандартный тип контента, например

application/json

вы говорите клиенту, что сообщение находится в формате JSON. Этого достаточно для всех веб-приложений, которые не поддерживают их API или поддерживают только последнюю версию. Если у вас будут клиенты, использующие разные версии вашего 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