Версионирование Публичного API

Документация описывает механизм версионирования Публичного API GitVerse. Этот механизм позволяет управлять изменениями в API, обеспечивая стабильность интеграций и предсказуемость поведения для всех пользователей.

Общее описание

В целях обеспечения стабильности, обратной совместимости и прозрачности изменений Публичный API GitVerse следует строгой политике версионирования на основе следующих принципов:

  1. Версионирование применяется ко всему API как единому целому (сквозная версия).
  2. Версия указывается только по MAJOR-номеру (например, 1, 2).
  3. Все изменения в API группируются и выпускаются как единая новая версия.
  4. Исправления ошибок (без изменения контракта) не требуют смены версии — они вносятся в последнюю выпущенную.
  5. Версии API не привязаны к внутренним версиям GitVerse.

Формат версии

Версия API — это целое положительное число, соответствующее MAJOR-версии по семантике SemVer.

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

Версия передается в заголовке Accept в следующем формате:

Accept: application/vnd.gitverse.object+json; version=1

⚠️ Важно: Указание версии обязательно. Если заголовок отсутствует или содержит недопустимое значение — запрос завершится ошибкой 400 Bad Request.

💡 Примечание: В текущей версии API используется значение version=1. Все минорные обновления (например, 1.1, 1.2, 1.5) относятся к ней и не требуют смены заголовка.

Поддержка и жизненный цикл версий

  1. Новая версия API сосуществует с предыдущей в течение 6 месяцев.
  2. После этого предыдущая версия выводится из эксплуатации.
  3. При запросе устаревшей (но еще поддерживаемой) версии API в ответе возвращаются специальные заголовки:
Gitverse-Api-Deprecation: true
Gitverse-Api-Decommissioning: 2027-06-30
Gitverse-Api-Latest-Version: 1
  1. При запросе уже выведенной из эксплуатации версии возвращается ошибка:
HTTP/1.1 400 Bad Request
Gitverse-Api-Latest-Version: 1

Документация и спецификации OpenAPI (Swagger)

Для каждой версии API публикуется отдельный файл спецификации в формате OpenAPI 2.0.
Файлы размещаются в публичном репозитории GitVerse:
🔗 rest-api-description

Структура репозитория:

/v1/openapi-1.0.json
/v1/openapi-1.1.json
/v1/openapi-1.2.json
/v1/openapi-1.3.json
/v1/openapi-1.4.json
/v1/openapi-1.5.json

Эти файлы можно использовать для генерации клиентских SDK, автоматического тестирования и интеграции в инструменты вроде Postman или Swagger UI.

Примеры URL-адресов спецификаций для версии 1:

  • https://gitverse.ru/gitverse/rest-api-description/v1/openapi-1.0.json;
  • https://gitverse.ru/gitverse/rest-api-description/v1/openapi-1.5.json.

Для версии 2 (будущая):

  • https://gitverse.ru/gitverse/rest-api-description/v2/openapi-2.0.json.

Связь между версией API и версией спецификации OpenAPI

Хотя версионирование API использует только MAJOR-номер (например, 1, 2), внутри каждой MAJOR-версии могут выпускаться обновления спецификации OpenAPI для:

  • выпуска обратно совместимых изменений;
  • уточнения описаний полей и параметров;
  • исправления опечаток или неточностей;
  • добавления примеров или улучшения документации.

Такие обновления отражаются в минорной версии спецификации (например, 1.2 → 1.3 → 1.4 → 1.5), но:

  1. Все они относятся к одной и той же MAJOR-версии API — для доступа к ним используется заголовок version=1.
  2. Контракт API (эндпоинты, параметры, форматы ответов) остается полностью совместимым в рамках одной MAJOR-версии.
MAJOR-версия APIЗаголовок AcceptФайлы спецификации OpenAPI
1version=1openapi-1.0.json, openapi-1.1.json, openapi-1.2.json, openapi-1.5.json
2version=2openapi-2.0.json, openapi-2.1.json

💡 Важно: При запросе с version=1 вы всегда работаете с актуальным контрактом API v1, независимо от того, какая минорная версия спецификации является последней.

Рекомендации для пользователей

✅ Следуйте этим рекомендациям, чтобы избежать сбоев в интеграциях.

  1. Всегда явно указывайте версию через Accept-заголовок.
  2. Регулярно проверяйте заголовки ответа на наличие Gitverse-Api-Deprecation.
  3. Планируйте миграцию на новую версию в течение 6 месяцев после ее релиза.
  4. Следите за обновлениями в репозитории спецификаций и в официальной документации.

Примеры запросов и ответов

Запрос к актуальной (последней) версии API

curl -X GET 'https://api.gitverse.ru/user' \
  -H 'Accept: application/vnd.gitverse.object+json; version=1' \
  -H 'Authorization: Bearer <token>'

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Gitverse-Api-Version: 1
Gitverse-Api-Latest-Version: 1
 
{"id":"user123","name":"Alice"}

Запрос к устаревшей, но еще поддерживаемой версии (гипотетический пример)

curl -X GET 'https://api.gitverse.ru/user' \
  -H 'Accept: application/vnd.gitverse.object+json; version=0' \
  -H 'Authorization: Bearer <token>'

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Gitverse-Api-Version: 0
Gitverse-Api-Deprecation: true
Gitverse-Api-Decommissioning: 2026-06-30
Gitverse-Api-Latest-Version: 1
 
{"id":"user123","name":"Alice"}

⚠️ Обратите внимание на заголовки Gitverse-Api-Deprecation и Gitverse-Api-Decommissioning — они сигнализируют, что версия скоро будет отключена.

Запрос к выведенной из эксплуатации версии (гипотетический пример)

curl -X GET 'https://api.gitverse.ru/user' \
  -H 'Accept: application/vnd.gitverse.object+json; version=0' \
  -H 'Authorization: Bearer <token>'

Ответ:

HTTP/1.1 400 Bad Request
Gitverse-Api-Latest-Version: 1

❌ Версия больше не поддерживается. Необходимо обновить интеграцию до актуальной версии (version=1).

Вид графа

Связанные страницы