Я прочитал много сообщений о переполнении стека (и других) в службах 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: */*?
Любые дополнительные предложения приветствуются. Цель, конечно, состоит в том, чтобы разрешить изменения того, что служба возвращает для данного ресурса, но не нарушать существующих клиентов.
Вот краткий список ресурсов, которые я недавно просмотрел:
- Рекомендации по управлению версиями API
- Как использовать REST URI
- REST api versioning (только версия - представление, а не сам ресурс)
- http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
- http://www.subbu.org/blog/2008/05/avoid-versioning-please
- http://www.informit.com/articles/article.aspx?p=1566460
- http://en.wikipedia.org/wiki/Internet_media_type#Prefix_vnd
- http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1