1. Версионирование Публичного 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.

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

1. Новая версия API сосуществует с предыдущей в течение 6 месяцев.
2. После этого предыдущая версия выводится из эксплуатации.
3. При запросе устаревшей (но еще поддерживаемой) версии API в ответе возвращаются специальные заголовки:

Gitverse-Api-Deprecation: true
Gitverse-Api-Decommissioning: 2025-12-31
Gitverse-Api-Latest-Version: 2

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

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

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

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

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

/v1/openapi-1.0.json
/v1/openapi-1.1.json
/v1/openapi-1.2.json
/v2/openapi-2.0.json
/v2/openapi-2.1.json

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

Таким образом, полные URL-адреса спецификаций будут:

• версия 1: https://gitverse.ru/gitverse/rest-api-description/v1/openapi-1.0.json;
• версия 2: https://gitverse.ru/gitverse/rest-api-description/v2/openapi-2.0.json.

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

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

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

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

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

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

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=3' \
  -H 'Authorization: Bearer <token>'

Ответ:

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

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

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

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Gitverse-Api-Version: 2
Gitverse-Api-Deprecation: true
Gitverse-Api-Decommissioning: 2026-01-01
Gitverse-Api-Latest-Version: 3
 
{"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=1' \
  -H 'Authorization: Bearer <token>'

Ответ:

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

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