Versões da API

Sobre o controle de versão da API

A GitHub API REST é versionada. O nome da versão da API é baseado na data em que a versão da API foi lançada. Por exemplo, a versão 2026-03-10 da API foi lançada em Tue, 10 Mar 2026.

Alterações interruptivas são alterações que podem potencialmente interromper uma integração. Alterações significativas serão lançadas em uma nova versão da API. Forneceremos aviso prévio antes de liberar alterações significativas. As alterações interruptivas incluem:

Removendo uma operação inteira
Removendo ou renomeando um parâmetro
Removendo ou renomeando um campo de resposta
Adicionando um novo parâmetro obrigatório
Tornando necessário um parâmetro que era opcional
Alterando o tipo de um parâmetro ou campo de resposta
Removendo valores de enumeração
Adicionando uma nova regra de validação a um parâmetro existente
Alterando os requisitos de autenticação ou autorização

Quaisquer mudanças aditivas (não disruptivas) estarão disponíveis em todas as versões da API suportadas. Alterações aditivas são alterações que não devem interromper uma integração. As alterações aditivas incluem:

Adicionando uma operação
Adicionando um parâmetro opcional
Adicionando um cabeçalho de solicitação opcional
Adicionando um campo de resposta
Adicionando um cabeçalho de resposta
Adicionando valores de enumeração

Quando uma nova versão da API REST for lançada, a versão anterior da API terá suporte por pelo menos mais 24 meses após o lançamento da nova versão da API.

Sobre o controle de versões de GitHub Enterprise Server e o controle de versões da API REST

          GitHub Enterprise Server as versões estão desacopladas das versões da API REST. Você pode atualizar sua GitHub Enterprise Server versão, mas manter a mesma versão da API REST, desde que a versão da API seja incluída na GitHub Enterprise Server versão. Da mesma forma, você pode atualizar sua versão da API REST sem atualizar sua GitHub Enterprise Server versão, desde que a nova versão da API REST escolhida esteja disponível para sua GitHub Enterprise Server versão.

As GitHub Enterprise Server notas de versão serão declaradas quando uma versão da API REST não tiver mais suporte. Para saber mais, confira Notas de versão.

Especificando uma versão da API

Você deve usar o cabeçalho X-GitHub-Api-Version para especificar uma versão da API. Por exemplo:

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

As solicitações sem o cabeçalho X-GitHub-Api-Version padrão usarão a versão 2022-11-28.

Se você especificar uma versão da API que não tem mais suporte, receberá uma 410 Gone resposta.

Atualizando para o nova versão da API

Antes de atualizar para uma nova versão da API REST, leia o log de alterações significativas da nova versão da API para entender quais mudanças significativas estão incluídas e como atualizar para essa versão específica da API. Para saber mais, confira Alterações de quebra.

Ao atualizar sua integração para especificar a nova versão da API no cabeçalho X-GitHub-Api-Version, você também precisará fazer as alterações necessárias para que sua integração funcione com a nova versão da API.

Após a atualização da integração, teste sua integração para verificar se ela funciona com a nova versão da API.

Versão da API encerrando

Há suporte para versões de API por 24 meses após o lançamento de uma versão mais recente da API.

Embora uma versão esteja dentro de sua janela de suporte, mas se aproximando encerrando, GitHub inclui os seguintes cabeçalhos em respostas à API para ajudá-lo a se preparar para a migração:

Deprecation — A data em que a versão da API será encerrandoformatada como uma data HTTP por RFC 7231. Por exemplo: Wed, 27 Nov 2019 14:34:29 GMT.
Sunset — A data em que a versão da API será completamente removida (descontinuado), após a qual as solicitações retornarão uma 410 Gone resposta. Segue RFC 8594. Por exemplo: Fri, 27 Nov 2020 14:34:29 GMT.

Após o término da janela de suporte:

As solicitações que especificam uma encerrando versão da API recebem uma 410 Gone resposta.
Solicitações que não especificam uma versão de API padrão são definidas por padrão para a próxima versão com suporte mais antiga, não a versão encerrando. Se você depender de solicitações não versionadas, poderá observar alterações comportamentais à medida que as versões mais antigas deixarem de ser suportadas.

Para obter mais informações sobre como migrar para uma versão mais recente da API, consulte Alterações de quebra.

Exceções ao versionamento padrão

Em casos raros, GitHub pode fazer alterações fora da cadência normal de controle de versão da API. Essas são intervenções excepcionais que não alteram as garantias de controle de versão padrão para a maioria dos integradores.

Problemas de segurança, disponibilidade e confiabilidade

Vulnerabilidades críticas de segurança, riscos de exposição de dados ou problemas graves de confiabilidade podem exigir alterações fora do agendamento normal de lançamento. GitHub pode liberar uma versão de API não programada, correções de backport para versões com suporte ou, em casos raros, introduzir uma alteração significativa em uma versão existente para proteger os usuários e a integridade da plataforma.

          GitHub comunicará essas alterações por meio de notas de versão, changelogs e comunicação direta explicando o que mudou e por quê. Quando possível, o aviso prévio será fornecido. A ação imediata pode ser tomada sem aviso prévio quando necessário.

Serviços de baixo uso

Para determinados serviços com uso muito baixo, GitHub pode descontinuar a funcionalidade fora do processo padrão de controle de versão. Nesses casos, GitHub comunicará a intenção e entrará em contato diretamente com os integradores afetados.

Versões de API com suporte

Atualmente, há suporte para as seguintes versões da API REST.

Versão da API	Data de término do suporte
`2022-11-28`	March 10, 2028

Você também pode fazer uma solicitação de API para obter todas as versões de API com suporte. Para saber mais, confira Pontos de extremidade da API REST para metadados.

Neste artigo