Зачем интерфейсу нужны версии
Интерфейс развивается: меняются поля, появляются новые возможности, исчезают устаревшие. Если просто изменить существующий адрес, все приложения, которые на нём работают, сломаются одновременно. Версионирование позволяет выпускать изменения постепенно, оставляя старую версию доступной на переходный период.
Основные способы указать версию
- в пути адреса:
/api/v1/products; - в параметре запроса:
/api/products?version=1; - в заголовке запроса, не меняя сам адрес.
Для большинства проектов удобнее всего первый вариант: версия видна в адресе, её легко прочитать в журнале и проверить вручную.
Что считать несовместимым изменением
- удаление или переименование поля в ответе;
- изменение типа значения или формата даты;
- изменение порядка или обязательности параметров запроса.
Добавление нового необязательного поля обычно совместимо и не требует новой версии.
Как устаревает старая версия
Заранее объявите срок поддержки, добавьте к ответам старой версии предупреждающий заголовок и отслеживайте, кто ещё обращается к ней. Только когда обращений практически не остаётся, версию можно отключать, а её адреса — отдавать с кодом 410, как принято для окончательно удалённого содержимого.
Как это связано с индексацией
Важно: все версии API находятся в закрытой от индексации зоне. Публичные страницы сайта не должны содержать в адресе номер версии интерфейса.
Документация для каждой версии
Каждая версия интерфейса должна иметь собственное описание с перечнем адресов, параметров и форматов ответов. Пользователь, работающий с версией первой, не должен натыкаться на описание версии третьей. Полезно вести журнал изменений, где явно указано, что именно поменялось между версиями.
- отдельная страница документации для каждой версии;
- журнал изменений с датами;
- явные отметки об устаревших возможностях.
Совместимость и возможность отката
Новая версия развёртывается рядом со старой, а не вместо неё. Если обнаружится ошибка, клиенты продолжат работать на прежней версии, а вы спокойно исправите проблему. Такая схема стоит дополнительных ресурсов, но избавляет от аварий, когда изменения ломают чужие приложения.
Наблюдение за использованием версий
Прежде чем отключать старую версию, нужно знать, кто ещё ею пользуется. Считайте обращения к каждой версии по дням и, если есть возможность, по клиентам. Когда график старой версии приближается к нулю, можно предупредить оставшихся пользователей и назначить окончательную дату отключения.
Частые вопросы
Какой способ версионирования API самый удобный?
Версия в пути адреса: она наглядна, легко читается в журнале запросов и проверяется вручную.
Когда нужно выпускать новую версию API?
При несовместимых изменениях, например удалении поля или смене формата данных; добавление необязательного поля обычно версию не требует.
Что делать с адресами устаревшей версии?
После окончания срока поддержки их отключают, отдавая код 410 для окончательно удалённых адресов.
Готовый адрес можно собрать прямо сейчас: откройте генератор ЧПУ — он транслитерирует фразу по таблице Яндекса, уберёт служебные слова и покажет длину адреса.