Introdução à API REST

Introdução

Este artigo descreve como usar a API REST do GitHub com GitHub CLI, curl ou JavaScript. Para ver um guia de início rápido, confira Início Rápido para a API REST do GitHub.

Sobre solicitações para a API REST

Esta seção descreve os elementos que compõem uma solicitação de API:

Método HTTP
Caminho
Cabeçalhos
Tipos de mídia
Autenticação
Parâmetros

Cada solicitação para a API REST inclui um método HTTP e um caminho. Dependendo do ponto de extremidade da API REST, talvez você também precise especificar cabeçalhos de solicitação, informações de autenticação, parâmetros de consulta ou parâmetros de corpo.

A documentação de referência da API REST descreve o método HTTP, o caminho e os parâmetros para cada ponto de extremidade. Ela também exibe exemplos de solicitações e respostas para cada ponto de extremidade. Para mais informações, confira a documentação de referência de REST.

Método HTTP

O método HTTP de um ponto de extremidade define o tipo de ação que ele executa em um determinado recurso. Alguns métodos HTTP comuns são GET, POST, DELETE e PATCH. A documentação de referência da API REST fornece o método HTTP para cada ponto de extremidade.

Por exemplo, o método HTTP para o ponto de extremidade "Listar problemas do repositório" é GET.

Sempre que possível, a API REST do GitHub tenta usar um método HTTP apropriado para cada ação.

GET: usado para recuperar recursos.
POST: usado para criar recursos.
PATCH: usado para atualizar propriedades de recursos.
PUT: usado para substituir recursos ou coleções de recursos.
DELETE: usado para excluir recursos.

Caminho

Cada ponto de extremidade tem um caminho. A documentação de referência da API REST fornece o caminho para cada ponto de extremidade. Por exemplo, o caminho para o ponto de extremidade "Listar problemas do repositório" é /repos/{owner}/{repo}/issues.

As chaves {} em um caminho denotam os parâmetros de caminho que precisam ser especificados por você. Os parâmetros de caminho modificam o caminho do ponto de extremidade e são necessários em sua solicitação. Por exemplo, os parâmetros de caminho para o ponto de extremidade "Listar problemas do repositório" são {owner} e {repo}. Para usar esse caminho em sua solicitação de API, substitua {repo} pelo nome do repositório no qual você deseja solicitar uma lista de problemas e substitua {owner} pelo nome da conta proprietária do repositório.

Cabeçalhos

Os cabeçalhos fornecem informações adicionais sobre a solicitação e a resposta desejada. Veja a seguir alguns exemplos de cabeçalhos que você pode usar em suas solicitações para a API REST do GitHub. Para obter um exemplo de uma solicitação que usa cabeçalhos, consulte Fazer uma solicitação.

`Accept`

A maioria dos pontos de extremidade da API REST do GitHub especifica que você deve transmitir um cabeçalho Accept com um valor de application/vnd.github+json. O valor do cabeçalho Accept é um tipo de mídia. Para obter mais informações sobre os tipos de mídia, confira Tipos de mídia.

`X-GitHub-Api-Version`

Você deve usar esse cabeçalho para especificar uma versão da API REST a ser usada para sua solicitação. Para saber mais, confira Versões da API.

`User-Agent`

Todas as solicitações de API precisam incluir um cabeçalho User-Agent válido. O cabeçalho User-Agent identifica o usuário ou aplicativo que está fazendo a solicitação.

Por padrão, a GitHub CLI envia um cabeçalho User-Agent válido. No entanto, o GitHub recomenda usar o nome de usuário do GitHub ou o nome do aplicativo para o valor do cabeçalho User-Agent. Isso permite que GitHub entre em contato com você se houver problemas.

Por padrão, curl envia um cabeçalho User-Agent válido. No entanto, o GitHub recomenda usar o nome de usuário do GitHub ou o nome do aplicativo para o valor do cabeçalho User-Agent. Isso permite que GitHub entre em contato com você se houver problemas.

Se você usar o SDK Octokit.js, o SDK enviará um cabeçalho User-Agent válido para você. No entanto, o GitHub recomenda usar o nome de usuário do GitHub ou o nome do aplicativo para o valor do cabeçalho User-Agent. Isso permite que GitHub entre em contato com você se houver problemas.

Veja a seguir um exemplo de User-Agent para um aplicativo chamado Awesome-Octocat-App:

User-Agent: Awesome-Octocat-App

Solicitações sem cabeçalho User-Agent serão rejeitadas. Se você fornecer um cabeçalho User-Agent inválido, receberá uma resposta 403 Forbidden.

Tipos de mídia

Você pode especificar um ou mais tipos de mídia adicionando-os ao cabeçalho Accept de sua solicitação. Para obter mais informações sobre o cabeçalho Accept, confira Accept.

Os tipos de mídia especificam o formato dos dados que você deseja consumir da API. Os tipos de mídia são específicos aos recursos, permitindo que eles mudem de forma independente e ofereçam suporte a formatos que outros recursos não. A documentação de cada ponto de extremidade da API REST do GitHub descreverá os tipos de mídia compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Os tipos de mídia mais comuns compatíveis com a API REST do GitHub são application/vnd.github+json e application/json.

Existem tipos de mídia personalizados que você pode usar com alguns pontos de extremidade. A API REST, por exemplo, para gerenciar commits e pull requests, oferece suporte aos tipos de mídia diff, patch e sha. Os tipos de mídia full, raw, text ou html são usados por alguns outros pontos de extremidade.

Todos os tipos de mídias personalizadas no GitHub são semelhantes ao seguinte: application/vnd.github.PARAM+json, em que PARAM é o nome do tipo de mídia. Por exemplo, para especificar o tipo de mídia raw, você poderia usar application/vnd.github.raw+json.

Para obter um exemplo de uma solicitação que usa tipos de mídia, confira Fazer uma solicitação.

Autenticação

Muitos pontos de extremidade exigem autenticação ou retornam informações adicionais se você estiver autenticado. Além disso, você pode fazer mais solicitações por hora quando estiver autenticado.

Para autenticar sua solicitação, você precisará fornecer um token de autenticação com os escopos ou as permissões necessários. Existem algumas maneiras diferentes de obter um token: você pode criar um personal access token, gerar um token com um GitHub App ou usar o GITHUB_TOKEN interno em um fluxo de trabalho do GitHub Actions. Para saber mais, confira Autenticação na API REST.

Para obter um exemplo de uma solicitação que usa um token de autenticação, confira Fazer uma solicitação.

Observação

Se não quiser criar um token, você poderá usar a GitHub CLI. A GitHub CLI cuidará da autenticação para você e ajudará a manter sua conta segura. Para obter mais informações, confira a versão desta página para a GitHub CLI.

Aviso

Trate seu token de acesso da mesma forma que trataria suas senhas ou outras credenciais confidenciais. Para saber mais, confira Manter suas credenciais de API seguras.

Embora alguns pontos de extremidade da API REST sejam acessíveis sem autenticação, a GitHub CLI requer que você se autentique antes de usar o subcomando api para fazer uma solicitação de API. Use o subcomando auth login para autenticar-se no GitHub. Para saber mais, confira Fazer uma solicitação.

Para obter um exemplo de uma solicitação que usa um token de autenticação, confira Fazer uma solicitação.

Aviso

Trate seu token de acesso da mesma forma que trataria suas senhas ou outras credenciais confidenciais. Para saber mais, confira Manter suas credenciais de API seguras.

Parâmetros

Muitos métodos de API exigem ou permitem que você envie informações adicionais em parâmetros em sua solicitação. Existem alguns tipos diferentes de parâmetros: parâmetros de caminho, parâmetros de corpo e parâmetros de consulta.

Parâmetros de caminho

Os parâmetros de caminho modificam o caminho do ponto de extremidade. Esses parâmetros são obrigatórios em sua solicitação. Para obter mais informações, consulte Caminho.

Parâmetros do corpo

Os parâmetros do corpo permitem que você passe dados adicionais para a API. Esses parâmetros podem ser opcionais ou obrigatórios, dependendo do ponto de extremidade. Por exemplo, um parâmetro de corpo pode permitir que você especifique um título de problema ao criar um novo problema ou especificar determinadas configurações ao habilitar ou desabilitar um recurso. A documentação de cada ponto de extremidade da API REST do GitHub descreverá os tipos de corpo compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Por exemplo, o ponto de extremidade "Criar um problema" exige que você especifique um título para o novo problema em sua solicitação. Ele também permite que você especifique outras informações opcionalmente, como texto para colocar no corpo do problema, usuários para atribuir ao novo problema ou rótulos para aplicar ao novo problema. Para obter um exemplo de uma solicitação que usa parâmetros de corpo, confira Fazer uma solicitação.

Para transmitir parâmetros de corpo, você deverá autenticar sua solicitação. Para obter mais informações, confira Autenticação.

Parâmetros de consulta

Os parâmetros de consulta permitem controlar quais dados são retornados para uma solicitação. Geralmente, esses parâmetros são opcionais. A documentação de cada ponto de extremidade da API REST do GitHub descreverá quaisquer parâmetros de consulta compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Por exemplo, o ponto de extremidade "Listar eventos públicos" retorna trinta problemas por padrão. Você pode usar o parâmetro de consulta per_page para retornar dois problemas em vez de 30. Você pode usar o parâmetro de consulta page para buscar apenas a primeira página de resultados. Para obter um exemplo de uma solicitação que usa parâmetros de consulta, consulte Fazer uma solicitação.

Para se autenticar no GitHub, execute o comando a seguir no terminal.
```
gh auth login
```
Você pode usar a opção --scopes para especificar os escopos desejados. Se você quiser autenticar com um token criado, poderá usar a opção --with-token. Para obter mais informações, confira a documentaçãoauth login da GitHub CLI.
Selecione o local em que deseja se autenticar:
- Se você acessar o GitHub no GitHub.com, selecione GitHub.com.
- Se você acessar o GitHub em um domínio diferente, selecione Outro e depois insira o nome do host (por exemplo, octocorp.ghe.com).
Siga o restante das solicitações na tela.

O GitHub CLI armazena automaticamente suas credenciais do Git quando você escolhe HTTPS como protocolo preferencial para operações Git e responde "sim" ao prompt que pergunta se deseja efetuar a autenticação no Git com suas credenciais do GitHub. Isso pode ser útil porque permite que você use comandos Git como git push e git pull sem a necessidade de configurar um gerenciador de credenciais distinto ou usar SSH.

3. Escolher um ponto de extremidade para sua solicitação

Escolha um ponto de extremidade para o qual fazer uma solicitação. É possível consultar a documentação da API REST do GitHub para descobrir pontos de extremidades que possam ser usados para interagir com o GitHub.
Identifique o método HTTP e o caminho do ponto de extremidade. Você vai enviá-los com sua solicitação. Para obter mais informações, consulte Método HTTP e Caminho.

Por exemplo, o ponto de extremidade "Criar um problema" usa o método HTTP POST e o caminho /repos/{owner}/{repo}/issues.
Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes {} no caminho do ponto de extremidade. Substitua cada espaço reservado do parâmetro pelo valor desejado. Para obter mais informações, consulte Caminho.

Por exemplo, o ponto de extremidade "Criar um problema" usa o caminho /repos/{owner}/{repo}/issues e os parâmetros de caminho são {owner} e {repo}. Para usar esse caminho em sua solicitação de API, substitua {repo} pelo nome do repositório no qual deseja criar um novo problema e substitua {owner} pelo nome da conta proprietária do repositório.

4. Fazer uma solicitação com a GitHub CLI

Use o subcomando api da GitHub CLI para fazer sua solicitação de API. Para obter mais informações, confira a documentaçãoapi da GitHub CLI.

Em sua solicitação, especifique as seguintes opções e valores:

--method seguido pelo método HTTP e o caminho do ponto de extremidade. Para obter mais informações, consulte Método HTTP e Caminho.
--header:
- Accept: passe o tipo de mídia em um cabeçalho Accept. Para transmitir vários tipos de mídia em um cabeçalho Accept, separe os tipos de mídia com uma vírgula: Accept: application/vnd.github+json,application/vnd.github.diff. Para obter mais informações, confira Accept e