Типы поставщиков MIME (для версий версий API)
Я прочитал много сообщений о переполнении стека (и других) в службах RESTful для управления версиями.
Честно говоря, это немного подавляющее.
Я решил использовать заголовок Accept: для нашего (маргинального) сервиса RESTful, чтобы клиенты могли запрашивать определенные версии ресурса. Я не понимаю, что указать в заголовке Accept.
Пример, который я часто видел, следующий:
Accept: application/vnd.mycompany.myapp.customer-v2+json
Мои вопросы:
-
Я исправлю, что все типы vnd должны быть зарегистрированы? (http://www.iana.org/cgi-bin/mediatypes.pl)
-
Является ли версия и тип (т.е. -v2 + json) частью типа, и поэтому каждая версия и тип должны быть зарегистрированы?
-
Есть ли какая-нибудь причина использовать vnd вместо подтипа "x-", который не нужно регистрировать? Например:
Accept: application/x-mycompany.myapp-v2+json
Существующий API является только внутренним, но в будущем он будет доступен клиентам.
-
Не уверен, что это имеет смысл, но можно ли использовать существующий тип, но добавить версию? (Текущий API возвращает "application/json" )
Accept: application/json-v2
-
Какие приемлемые форматы для добавления версии и типа (например, -v2 + json).
-
Что делать, если клиент запрашивает не поддерживаемую версию? Правильный ответ 406? Может ли клиент запросить любую версию? Или, в общем, что, если клиент не предоставляет заголовок Accept или Accept: */*?
Любые дополнительные предложения приветствуются. Цель, конечно, состоит в том, чтобы разрешить изменения того, что служба возвращает для данного ресурса, но не нарушать существующих клиентов.
Вот краткий список ресурсов, которые я недавно просмотрел:
Ответы
Ответ 1
Как я решил следовать стандарту jsonapi.org, я решил сделать то, что показывает ваш пример.
Относительно ваших вопросов:
- Ваш тип MIME должен быть зарегистрирован
- Я считаю, что каждая версия и тип должны быть зарегистрированы, поскольку они являются уникальными типами
Префикс
-
x-
устарел, как отмечено в комментарии
-
application/json-v2
недействителен
- Вы можете вернуть
415 Unsupported Media Type
или просто 400 Bad Request