Sobre o controle de versão da API
A API REST do GitHub tem controle de versão. 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 2022-11-28 da API foi lançada em Mon, 28 Nov 2022.
Quaisquer alterações interruptivas serão lançadas em uma nova versão da API. Alterações interruptivas são alterações que podem potencialmente interromper uma integração. 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
- fazendo um parâmetro opcional anteriormente necessário
- 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 alterações aditivas (não interruptivas) estarão disponíveis em todas as versões da API com suporte. 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.
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 usarão a versão 2022-11-28 padrão.
Se você especificar uma versão da API que não tem mais suporte, receberá um erro 400.
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 de alterações interruptivas da nova versão da API para entender quais alterações interruptivas estão incluídas e saber mais sobre 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ões de API com suporte
No momento, há suporte para as seguintes versões da API REST:
2022-11-28
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.