Версионирование Web API

Зачем нужно версионирование?

В ходе развития и совершенствования нашей системы, мы постоянно вносим какие-то изменения в Web API. Поскольку наше API используют разработчики не из Carrot quest, мы понимаем, что изменение методов API несет для них риски, что "все поломается". Поэтому мы стараемся никогда не вносить обратно несовместимых изменений в открытое API.
Однако бывают ситуации, когда это приходится делать, например, в целях повышения безопасности или исправления каких-то базовых механик. Чтобы никому ничего не сломать, вводится система версионирования: указав версию вы можете получить от API как старое, так и новое поведение.

Что такое версия?

Версия - это последовательность цифр, которая определяет поведение API. Наша система следует схеме семантического версионирования.
Пример полной версии: 2.10.5.

Минорная и патч версии обратно совместимы. Поэтому, в публичном API мы описываем изменения только для мажорных версий (2 в примере).

Когда вы делаете запросы к API, вы можете указать не всю версию, а только ее "префикс". Тогда вы будете использовать наиболее позднюю минорную версию после вашего префикса. Положим, в API есть версии 1.0.0, 1.1.0, 2.0.0, 2.0.1, 2.1.0, 2.1.1. Если Вы укажете версию 2, то будете использовать 2.1.1. Если вы укажете 1, то будете использовать 1.1.0.

Как указать версию при запросе

Указать версию можно одним из 2 способов:

  • С помощью префикса URL (обратите внимание на v1 и v2 в начале URL-пути)
    • GET https://api.carrotquest.io/v1/users/123
    • POST https://api.carrotquest.io/v2/users/props
  • С помощью GET или POST параметра version
    • GET https://api.carrotquest.io/users/123?version=2

Важно! Если вы не указываете версию, используется текущая актуальная версия API.

Актуальные версии API и изменения

Текущая мажорная версия API (используется по умолчанию): 2

Версия 3 (v3, будущая)

Переход авторизации на JWT-токены. Все методы API, генерирующие токены авторизации теперь возвращают словарь с полями access_token, refresh_token вместо строкового токена.

Версия 2 (v2, по умолчанию)

Изменена схема пагинации запросов.

Версия 1 (v1, устаревшая)

Изначальная версия API.