Версии API

Узнайте, как указать, какую версию REST API следует использовать при каждом запросе к REST API.

В этой статье

Сведения о управлении версиями API

GitHub REST API имеет версии. Имя версии API основано на дате выпуска версии API. Например, версия 2026-03-10 API была выпущена на Tue, 10 Mar 2026.

Критические изменения — это изменения, которые могут потенциально нарушить интеграцию. Срочные изменения будут выпущены в новой версии API. Мы предупредим заранее перед публикацией нерешительных изменений. Критические изменения включают:

  • Удаление всей операции
  • Удаление или переименование параметра
  • Удаление или переименование поля ответа
  • Добавление нового обязательного параметра
  • Создание ранее необязательного параметра
  • Изменение типа поля параметра или ответа
  • Удаление значений перечисления
  • Добавление нового правила проверки в существующий параметр
  • Изменение требований к проверке подлинности или авторизации

Любые некритивные изменения будут доступны во всех поддерживаемых версиях API. Аддитивные изменения — это изменения, которые не должны прерывать интеграцию. К аддитивным изменениям относятся:

  • Добавление операции
  • Добавление необязательного параметра
  • Добавление необязательного заголовка запроса
  • Добавление поля ответа
  • Добавление заголовка ответа
  • Добавление значений перечисления

При выпуске новой версии REST API предыдущая версия API будет поддерживаться не менее 24 месяцев после выпуска новой версии API.

Указание версии API

Вам следует использовать заголовок X-GitHub-Api-Version для указания версии API. Например:

curl --header "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen

Запросы без заголовка X-GitHub-Api-Version по умолчанию будут использовать версию 2022-11-28.

Если вы укажете версию API, которая больше не поддерживается, вы получите 410 Gone ответ.

Обновление до новой версии API

Перед обновлением до новой версии REST API необходимо прочитать журнал изменений критических изменений для новой версии API, чтобы понять, какие критические изменения включены и узнать больше о том, как обновить эту версию API. Дополнительные сведения см. в разделе Критические изменения.

Когда вы обновляете интеграцию, чтобы указать новую версию API в заголовке X-GitHub-Api-Version, вам также нужно внести необходимые изменения для работы с новой версией API.

После обновления интеграции проверьте интеграцию, чтобы убедиться, что она работает с новой версией API.

Версия API закрытие

Версии API поддерживаются в течение 24 месяцев после выхода новой версии API.

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

  • Deprecation — Дата, когда версия API будет закрытиеотформатирована как HTTP-дата согласно RFC 7231. Например: Wed, 27 Nov 2019 14:34:29 GMT.
  • Sunset — Дата, когда версия API будет полностью удалена (retired), после которой запросы вернут 410 Gone ответ. Следует RFC 8594. Например: Fri, 27 Nov 2020 14:34:29 GMT.

После окончания окна поддержки:

  • Запросы, указывающие закрытие версию API, получают 410 Gone ответ.
  • Запросы, которые не указывают версию API по умолчанию для следующей старейшей поддерживаемой версии, а не самой закрытие версии. Если вы полагаетесь на неверсионные запросы, вы можете наблюдать изменения в поведении, когда старые версии удаляются из поддержки.

Для получения дополнительной информации о миграции на более новую версию API см. AUTOTITLE.

Исключения из стандартной версии

В редких случаях GitHub могут вносить изменения вне обычной частоты версионирования API. Это исключительные вмешательства, которые не изменяют стандартные гарантии версионирования для большинства интеграторов.

Вопросы безопасности, доступности и надёжности

Критические уязвимости безопасности, риски раскрытия данных или серьёзные проблемы с надёжностью могут требовать изменений вне обычного графика выпуска. GitHub может выпустить незапланированную версию API, перепортить исправления поддерживаемых версий или, в редких случаях, внести нерешительное изменение существующей версии для защиты пользователей и целостности платформы.

          GitHub Будут сообщать об изменениях через заметки к релизу, журналы изменений и прямое объяснение, что и почему изменилось. По возможности будет предоставлено предварительное уведомление. При необходимости могут быть приняты немедленные меры без предварительного уведомления.

Сервисы с низким уровнем использования

Для некоторых сервисов с очень низким использованием они GitHub могут устарять функциональность вне стандартного процесса версионирования. В таких случаях GitHub они сообщают о намерении и напрямую свяжутся с затронутыми интеграторами.

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

В настоящее время поддерживаются следующие версии REST API.

Версия APIДата окончания поддержки
2026-03-10Not yet scheduled
2022-11-28March 10, 2028

Вы также можете запросить API, чтобы получить все поддерживаемые версии API. Дополнительные сведения см. в разделе Конечные точки REST API для метаданных.