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

Документация описывает механизм версионирования Публичного API GitVerse. Версионирование позволяет управлять изменениями в API, обеспечивая стабильность интеграций и предсказуемость поведения для всех пользователей. Текущая актуальная версия — version=1.

Политика версионирования API

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

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

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

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

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

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

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

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

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

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

Каждая версия API проходит через определенные стадии жизненного цикла. Понимание этих стадий помогает спланировать миграцию интеграций.

Поддерживаемые версии

Новая версия API сосуществует с предыдущей в течение 6 месяцев после релиза. В этот период обе версии работают одновременно.

Устаревшие версии

При запросе устаревшей (но еще поддерживаемой) версии API сервер возвращает специальные заголовки, предупреждающие о скором отключении:

Gitverse-Api-Deprecation: true
Gitverse-Api-Decommissioning: 2027-06-30
Gitverse-Api-Latest-Version: 1

• Gitverse-Api-Deprecation: true — сигнализирует, что текущая версия API объявлена устаревшей;
• Gitverse-Api-Decommissioning — дата вывода версии из эксплуатации;
• Gitverse-Api-Latest-Version — номер актуальной версии API, на которую следует мигрировать.

Выведенные из эксплуатации версии

После истечения периода сосуществования предыдущая версия API выводится из эксплуатации. При запросе уже выведенной из эксплуатации версии возвращается ошибка:

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

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

Спецификации OpenAPI (OpenAPI Specifications / Swagger)

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

Текущая структура репозитория для версии 1:

/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.

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

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

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

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

1. Все они относятся к одной и той же MAJOR-версии API — для доступа к ним используется заголовок version=1.
2. Контракт API (эндпоинты, параметры, форматы ответов) остается полностью совместимым в рамках одной MAJOR-версии.

MAJOR-версия API	Заголовок Accept	Файлы спецификации OpenAPI
1	version=1	openapi-1.0.json, openapi-1.1.json, openapi-1.2.json, openapi-1.5.json

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

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

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

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

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

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

Запрос к текущей актуальной версии (version=1) возвращает стандартный успешный ответ:

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"}

Заголовок Gitverse-Api-Version: 1 подтверждает версию API, с которой был обработан запрос. Заголовок Gitverse-Api-Latest-Version: 1 указывает на то, что используется самая свежая версия.

Запрос к устаревшей версии API — иллюстративный пример

ℹ️ В данный момент существует только одна версия API (version=1). Приведенный ниже пример иллюстрирует поведение системы, если бы существовала предыдущая версия.

При запросе к устаревшей, но еще поддерживаемой версии, сервер возвращает данные вместе с предупреждающими заголовками:

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: true и Gitverse-Api-Decommissioning — они сигнализируют, что версия скоро будет отключена. Необходимо мигрировать на version=1 до указанной даты.

Запрос к выведенной из эксплуатации версии — иллюстративный пример

ℹ️ В данный момент существует только одна версия API (version=1). Приведенный ниже пример иллюстрирует поведение системы для версий, уже выведенных из эксплуатации.

При запросе к выведенной из эксплуатации версии сервер возвращает ошибку 400 Bad Request:

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). Заголовок Gitverse-Api-Latest-Version указывает номер версии, на которую следует перейти.