Comments 20
Возможно, я не туда смотрю, но тут: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html не написано, что можно добавлять version=2 или подобное по своему усмотрению, там четко написано:
А ещё можно использовать q для указания приоритета.
Учитывая это, и первый из ресурсов что вы указали, я бы использовал заголовок Accepts-version (или лучше даже Accept-Version, по аналогии с Accept-Encoding, Accept-Language), который не привязан к стандарту и никому мешать не должен.
The Accept request-header field can be used to specify certain media types which are acceptable for the response
А ещё можно использовать q для указания приоритета.
Учитывая это, и первый из ресурсов что вы указали, я бы использовал заголовок Accepts-version (или лучше даже Accept-Version, по аналогии с Accept-Encoding, Accept-Language), который не привязан к стандарту и никому мешать не должен.
Да, верное замечание. Гитхаб вообще версию прямо в vnd добавляет
application/vnd.github[.version].param[+json]
Тогда уж X-Accept-Version. X-овые заголовки показывают что они не стандартные. А то мало ли потом подо что Accept-Version заюзают.
«X-» заголовки deprecated.
И как по текущему стандарту тогда называются экспериментальные заголовки?
Почитал на эту тему. Моё мнение: как раз их Deprecated статус и тот факт, что они ранее использовались как песочница перед стандартиризацией — как раз именно X-хидеры шикарно подходят для application-specific заголовков. Их точно перед стандартиризирующей обкаткой не будут использовать — ибо Deprecated — но при этом все уже привыкли (до того как они стали Deprecated) — что «X-» — не стандартные. И два этих факта по-моему как раз отлично бы показывали, что этот заголовок вероятней всего используется только здесь.
Извиняюсь за сумбур.
Извиняюсь за сумбур.
Ну в том документе сказано именно о конвенции: «distinguished between standardized and unstandardized parameters by prefixing the names with the string „X-“. This document deprecates the convention».
Видимо причина, что если введут Accept-Version, а у нас X-Accept-Version, то это вызовет больше вопросов (почему добавили то, что уже есть? можно ли использовать Accept-Version вместо X-? и т.п.) у клиентов API, учитывая что REST API завязан на HTTP спецификации.
Видимо причина, что если введут Accept-Version, а у нас X-Accept-Version, то это вызовет больше вопросов (почему добавили то, что уже есть? можно ли использовать Accept-Version вместо X-? и т.п.) у клиентов API, учитывая что REST API завязан на HTTP спецификации.
А чем это лучше указания версии в ссылке?
site.ru/api/v2/method/call гораздо нагляднее и проще
site.ru/api/v2/method/call гораздо нагляднее и проще
А если у вас апи версионируется не цифрой, а датой? И если у вас в зависимости от даты отрабатывает разная версия апи?
Что делать если апи постоянно развивается?
Причем, как уже ниже сказали, меняя версию апи в URL — вы меняете ресурс. А если ресурс не менялся?
По сути вы просто получаете немного измененное его представление. Поэтому более логичными выглядят варианты с заголовками. ИМХО)
Что делать если апи постоянно развивается?
Причем, как уже ниже сказали, меняя версию апи в URL — вы меняете ресурс. А если ресурс не менялся?
По сути вы просто получаете немного измененное его представление. Поэтому более логичными выглядят варианты с заголовками. ИМХО)
Об этом и написана статья)
Из статьи: troyhunt.com
I agree the URL should not change: If we concur that the URL represents the resource then unless we’re trying to represent different versions of the resource itself then no, I don’t think the URL should change. The breaches for foo are always the breaches for foo and I don’t think that just because I change the data returned for foo that the location of foo should change.
(Перевод в кратце: Я не считаю правильным использовать номер версии в url т.к. url представляет ресурс и версия эта должна отражать версию ресурса, а не версию api)
Он своим же высказыванием опровергает свою позицию. Что такое api? Это тоже ресурс — не так ли? Тогда указывая версию api в url мы четко и ясно говорим что хотим конкретную версию ресурса api. И эта версия будет отличаться от другой версии. Отсюда вопрос — зачем городить огород с Accept Header если он, по сути только усложнит определение версии апи добавив лишнюю операцию парсинга строки. А если там нет версии? Тогда добавим туда условие, что нужно использовать последнюю версию! Афигеть! Дайте 2! =) Вы точно хотите этот лишний головняк?
I agree the URL should not change: If we concur that the URL represents the resource then unless we’re trying to represent different versions of the resource itself then no, I don’t think the URL should change. The breaches for foo are always the breaches for foo and I don’t think that just because I change the data returned for foo that the location of foo should change.
(Перевод в кратце: Я не считаю правильным использовать номер версии в url т.к. url представляет ресурс и версия эта должна отражать версию ресурса, а не версию api)
Он своим же высказыванием опровергает свою позицию. Что такое api? Это тоже ресурс — не так ли? Тогда указывая версию api в url мы четко и ясно говорим что хотим конкретную версию ресурса api. И эта версия будет отличаться от другой версии. Отсюда вопрос — зачем городить огород с Accept Header если он, по сути только усложнит определение версии апи добавив лишнюю операцию парсинга строки. А если там нет версии? Тогда добавим туда условие, что нужно использовать последнюю версию! Афигеть! Дайте 2! =) Вы точно хотите этот лишний головняк?
Один из вариантов реализации, тот же Troy Hunt заканчивает мысль статьи тем, что выбранная реализация, в общем-то, никак не влияет на успешность проекта.
Так про успешность и не говорим. Она мало зависит от версионирования апи, если апи само по себе толковое.
Тут скорее вопрос в простоте реализации для клиента и для сервера. И вариант с версией в url наиболее понятен и прост в реализации для всех сторон. Единственная сложность может возникнуть с минорными версиями типа «1.1», но это вообще плохая затея как по мне.
Тут скорее вопрос в простоте реализации для клиента и для сервера. И вариант с версией в url наиболее понятен и прост в реализации для всех сторон. Единственная сложность может возникнуть с минорными версиями типа «1.1», но это вообще плохая затея как по мне.
Другой URL = другой ресурс. Не?
А что такое API? Разве API — не ресурс?
В моем понимании — API это корневой ресурс, который предоставляет доступ к другим ресурсам. Да, согласен, что другие ресурсы не принадлежат API физически (в БД или ФС), но оно все же не перестает быть ресурсом.
В моем понимании — API это корневой ресурс, который предоставляет доступ к другим ресурсам. Да, согласен, что другие ресурсы не принадлежат API физически (в БД или ФС), но оно все же не перестает быть ресурсом.
Допустим у вас есть ресурс — документ. В первой версии server.com/api/v1/documents/1, а во второй server.com/api/v2/documents/1. С точки зрения ресурсной модели — это 2 разных ресурса — хотя по сути один и тот же.
Ни и как выше писал, что делать если количество версий вашего апи не 1 или 2? Если Ваш апи развивается постоянно и клиенту необходимо точно знать с какой версией от какого числа он может работать? Имхо у Гитхаба весьма удобный способ версионирования — habrahabr.ru/post/240817/#comment_8087449. Он позволяет гибко работать с клиентом, причем даже с несколькими версиями апи одновременно.
Ни и как выше писал, что делать если количество версий вашего апи не 1 или 2? Если Ваш апи развивается постоянно и клиенту необходимо точно знать с какой версией от какого числа он может работать? Имхо у Гитхаба весьма удобный способ версионирования — habrahabr.ru/post/240817/#comment_8087449. Он позволяет гибко работать с клиентом, причем даже с несколькими версиями апи одновременно.
Согласен, что там может быть 2 одинаковых документа, но находятся-то они в разных корневых ресурсах. Причем часто они будут отличатся.
Как по мне инкрементировать версию апи имеет смысл если новая версия ресурсов значительно отличется от старой версии ресурсов. Добавляя новые русурсы нет смысла увеличивать версию апи. Поэтому меньшее количество ресурсов будут отдавать одинаковые данные.
На тему гитхаба — удобный, но далеко не всем проектам нужно изменять версию часто, т.е. опять же метод «не для всех».
И, кстати, ничто не мешает в обоих случаях использовать другу версию api. И, кстати, с точки зрения клиента проще использовать url, чем использовать один хедер для запросов к новому апи, а другой для запросов к старому апи. Шанс накосячить из-за невнимательности возрастает.
Тут как бы нет «серебрянной пули», каждый метод имеет свои плюсы и минусы. Нужно лишь правильно оценить потребности.
Как по мне инкрементировать версию апи имеет смысл если новая версия ресурсов значительно отличется от старой версии ресурсов. Добавляя новые русурсы нет смысла увеличивать версию апи. Поэтому меньшее количество ресурсов будут отдавать одинаковые данные.
На тему гитхаба — удобный, но далеко не всем проектам нужно изменять версию часто, т.е. опять же метод «не для всех».
И, кстати, ничто не мешает в обоих случаях использовать другу версию api. И, кстати, с точки зрения клиента проще использовать url, чем использовать один хедер для запросов к новому апи, а другой для запросов к старому апи. Шанс накосячить из-за невнимательности возрастает.
Тут как бы нет «серебрянной пули», каждый метод имеет свои плюсы и минусы. Нужно лишь правильно оценить потребности.
Для этого я расширил стандартные классы Router и RequestContext, новые классы я определил в parameters.yml
почему бы это же не сделать при помощи request-listener'а?
Sign up to leave a comment.
Использование Accept Header для версионирования API