Skip to main content

Introdução à API REST

Saiba como usar a API REST do GitHub.

Introdução

Este artigo descreve como usar a API REST do GitHub com a 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:

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 Enterprise Cloud tenta usar um método HTTP adequado 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 parâmetros de caminho que você precisa especificar. 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 obter mais informações, 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 seu nome de usuário do GitHub Enterprise Cloud, ou o nome de seu aplicativo, para o valor de 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 seu nome de usuário do GitHub Enterprise Cloud, ou o nome de seu aplicativo, para o valor de cabeçalho User-Agent. Isso permite que o 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 seu nome de usuário do GitHub Enterprise Cloud, ou o nome de seu aplicativo, para o valor de cabeçalho User-Agent. Isso permite que o 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ídia personalizados para o GitHub Enterprise Cloud têm a seguinte aparência: application/vnd.github.PARAM+json, com PARAM indicando 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, consulte "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 obter mais informações, confira "Autenticação na API REST".

Para obter um exemplo de uma solicitação que usa um token de autenticação, consulte "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 obter mais informações, 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 se autenticar no GitHub Enterprise Cloud. Para saber mais, confira "Fazer uma solicitação".

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 obter mais informações, confira "Autenticação na API REST".

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

Aviso: trate seu token de acesso da mesma forma que trataria suas senhas ou outras credenciais confidenciais. Para obter mais informações, 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, confira "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, consulte "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".

Como fazer uma solicitação

Esta seção demonstra como fazer uma solicitação autenticada para a API REST do GitHub usando a GitHub CLI.

1. Instalação

Instale a GitHub CLI no macOS, no Windows ou no Linux. Para obter instruções de instalação, confira Instalação no repositório do GitHub CLI.

2. Autenticar

  1. Autentique-se com GitHub executando este comando em seu terminal.

    Shell
    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.

  2. Siga os prompts 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

  1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub Enterprise Cloud para descobrir pontos de extremidade que você pode usar para interagir com o GitHub Enterprise Cloud.

  2. 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.

  3. 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, confira "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, consulte "Accept" e "Tipos de mídia".
    • X-GitHub-Api-Version: transmita a versão da API em um cabeçalho X-GitHub-Api-Version. Para obter mais informações, confira "X-GitHub-Api-Version".
  • -f ou -F seguido por quaisquer parâmetros de corpo ou parâmetros de consulta no formato key=value. Use a opção -F para transmitir um parâmetro que seja um número, booliano ou nulo. Use a opção -f para transmitir parâmetros de sequência.

    Alguns pontos de extremidade usam parâmetros de consulta que são matrizes. Para enviar uma matriz na cadeia de caracteres de consulta, use o parâmetro de consulta uma vez por item de matriz e acrescente [] após o nome do parâmetro de consulta. Por exemplo, para fornecer uma matriz de dois IDs de repositório, use -f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID.

    Se você não precisar especificar nenhum parâmetro de corpo ou parâmetro de consulta em sua solicitação, omita essa opção. Para obter mais informações, consulte "Parâmetros de corpo" e "Parâmetros de consulta". Para obter exemplos, consulte "Solicitação de exemplo usando parâmetros de corpo" e "Solicitação de exemplo usando parâmetros de consulta".

Solicitação de exemplo

A solicitação de exemplo a seguir usa o ponto de extremidade "Obter Octocat" para devolver o octocat como arte ASCII.

Shell
gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

Exemplo de solicitação usando parâmetros de consulta

O ponto de extremidade "Listar eventos públicos" retorna trinta problemas por padrão. O exemplo a seguir usa o parâmetro de consulta per_page para retornar dois problemas em vez de 30 e o parâmetro de consulta page para efetuar fetch apenas na primeira página de resultados.

Shell
gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

Exemplo de solicitação usando parâmetros do corpo

O exemplo a seguir usa o ponto de extremidade "Criar um issue" para criar um novo issue em um repositório the octocat/Spoon-Knife. Na resposta, localize o html_url do seu issue e acesse o issue no navegador.

Shell
gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

Esta seção demonstra como fazer uma solicitação autenticada para a API REST do GitHub usando curl.

1. Instalação

Você precisa ter o curl instalado no seu computador. Para verificar se o curl já está instalado, execute curl --version na linha de comando.

  • Se a saída fornecer informações sobre a versão do curl, isso significará que o curl está instalado.
  • Se você receber uma mensagem semelhante a command not found: curl, isso significará que o curl não está instalado. Baixe e instale o curl. Para obter mais informações, confira a página de download do curl.

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

  1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub Enterprise Cloud para descobrir pontos de extremidade que você pode usar para interagir com o GitHub Enterprise Cloud.

  2. 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.

  3. 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, confira "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.

3. Criar credenciais de autenticação

Crie um token de acesso para autenticar sua solicitação. Você pode salvar seu token e usá-lo para várias solicitações. Atribua ao token todos os escopos ou permissões necessários para acessar o ponto de extremidade. Você enviará esse token em um cabeçalho Authorization com sua solicitação. Para obter mais informações, confira "Autenticação".

4. Fazer uma solicitação curl

Use o comando curl para fazer sua solicitação. Para obter mais informações, consulte a documentação do curl.

Especifique as seguintes opções e valores em sua solicitação:

  • --request ou -X, seguido pelo método HTTP como o valor. Para obter mais informações, consulte "método HTTP".

  • --url seguido pelo caminho completo como o valor. O caminho completo é uma URL que inclui a URL base para a API REST do GitHub (https://api.github.com) e o caminho do ponto de extremidade, como este: https://api.github.com/PATH. Substitua PATH pelo caminho do ponto de extremidade. Para obter mais informações, confira "Caminho".

    Para usar parâmetros de consulta, adicione ? ao final do caminho e anexe o nome e o valor do parâmetro de consulta no formato parameter_name=value. Separe vários parâmetros de consulta com &. Se você precisar enviar uma matriz na cadeia de caracteres de consulta, use o parâmetro de consulta uma vez por item de matriz e acrescente [] após o nome do parâmetro de consulta. Por exemplo, para fornecer uma matriz de dois IDs de repositório, use ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID. Para saber mais, confira "Parâmetros de consulta". Para obter um exemplo, consulte "Exemplo de solicitação usando parâmetros de consulta".

  • --header ou -H:

    • Accept: transmita 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; por exemplo: Accept: application/vnd.github+json,application/vnd.github.diff. Para obter mais informações, consulte "Accept" e "Tipos de mídia".
    • X-GitHub-Api-Version: transmita a versão da API em um cabeçalho X-GitHub-Api-Version. Para obter mais informações, confira "X-GitHub-Api-Version".
    • Authorization: transmita seu token de autenticação em um cabeçalho Authorization. Observe que, na maioria dos casos, você pode usar Authorization: Bearer ou Authorization: token para transmitir um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer. Para obter mais informações, confira "Autenticação". Para obter um exemplo de solicitação com um cabeçalho Authorization, consulte "Exemplo de solicitação usando parâmetros de corpo".
  • --data ou -d seguido por quaisquer parâmetros de corpo dentro de um objeto JSON. Se você não precisar especificar nenhum parâmetro de corpo em sua solicitação, omita essa opção. Para obter mais informações, consulte "Parâmetros de corpo". Para obter um exemplo, consulte "Exemplo de solicitação usando parâmetros de corpo".

Solicitação de exemplo

A solicitação de exemplo a seguir usa o ponto de extremidade "Obter Octocat" para devolver o octocat como arte ASCII.

Shell
curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

Exemplo de solicitação usando parâmetros de consulta

O ponto de extremidade "Listar eventos públicos" retorna trinta problemas por padrão. O exemplo a seguir usa o parâmetro de consulta per_page para retornar dois problemas em vez de 30 e o parâmetro de consulta page para efetuar fetch apenas na primeira página de resultados.

Shell
curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

Exemplo de solicitação usando parâmetros do corpo

O exemplo a seguir usa o ponto de extremidade "Criar um issue" para criar um novo issue em um repositório the octocat/Spoon-Knife. Substitua YOUR-TOKEN pelo token de autenticação criado em uma etapa anterior.

Observação: se estiver usando um fine-grained personal access token, substitua octocat/Spoon-Knife por um repositório que pertença a você ou a uma organização da qual seja membro. O token precisa ter acesso a esse repositório e ter permissões de leitura e gravação para problemas de repositório. Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal".

Shell
curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

Esta seção demonstra como fazer uma solicitação para a API REST do GitHub usando JavaScript e Octokit.js. Para ver um guia mais detalhado, confira "Scripts com a API REST e o JavaScript".

1. Instalação

Você deve instalar o octokit para usar a biblioteca Octokit.js apresentada nos exemplos a seguir.

  • Instale o octokit. Por exemplo, npm install octokit. Para outras maneiras de instalar ou carregar octokit, confira o LEIA-ME do Octokit.js.

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

  1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub Enterprise Cloud para descobrir pontos de extremidade que você pode usar para interagir com o GitHub Enterprise Cloud.

  2. 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.

  3. 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, confira "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.

3. Criar um token de acesso

Crie um token de acesso para autenticar sua solicitação. Você pode salvar seu token e usá-lo para várias solicitações. Atribua ao token todos os escopos ou permissões necessários para acessar o ponto de extremidade. Você enviará esse token em um cabeçalho Authorization com sua solicitação. Para obter mais informações, confira "Autenticação".

4. Fazer uma solicitação com Octokit.js

  1. Importe octokit em seu script. Por exemplo, import { Octokit } from "octokit";. Para outras maneiras de importar octokit, confira o LEIA-ME do Octokit.js.

  2. Crie uma instância de Octokit com seu token. Substitua YOUR-TOKEN pelo seu token.

    JavaScript
    const octokit = new Octokit({ 
      auth: 'YOUR-TOKEN'
    });
    
  3. Use octokit.request para executar sua solicitação.

    • Envie o método HTTP e o caminho como o primeiro argumento do método request. Para obter mais informações, consulte "Método HTTP" e "Caminho".
    • Especifique todos os parâmetros de caminho, consulta e corpo em um objeto como o segundo argumento do método request. Para obter mais informações, confira "Parâmetros".

    No exemplo de solicitação a seguir, o método HTTP é POST, o caminho é /repos/{owner}/{repo}/issues, os parâmetros de caminho são owner: "octocat" e repo: "Spoon-Knife" e os parâmetros de corpo são title: "Created with the REST API" e body: "This is a test issue created by the REST API".

    Observação: se estiver usando um fine-grained personal access token, substitua octocat/Spoon-Knife por um repositório que pertença a você ou a uma organização da qual seja membro. O token precisa ter acesso a esse repositório e ter permissões de leitura e gravação para problemas de repositório. Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal".

    JavaScript
    await octokit.request("POST /repos/{owner}/{repo}/issues", {
      owner: "octocat",
      repo: "Spoon-Knife",
      title: "Created with the REST API",
      body: "This is a test issue created by the REST API",
    });
    

    O método request passa automaticamente o cabeçalho Accept: application/vnd.github+json. Para passar cabeçalhos adicionais ou um cabeçalho Accept diferente, adicione uma propriedade headers ao objeto que é passado como o segundo argumento. O valor da propriedade headers é um objeto com os nomes de cabeçalho como chaves e valores de cabeçalho como valores.

    Por exemplo, o código a seguir enviará um cabeçalho content-type com o valor text/plain e um cabeçalho X-GitHub-Api-Version com o valor 2022-11-28.

    JavaScript
    await octokit.request("GET /octocat", {
      headers: {
        "content-type": "text/plain",
        "X-GitHub-Api-Version": "2022-11-28",
      },
    });
    

Como usar a resposta

Depois que você fizer uma solicitação, a API retornará o código de status de resposta, os cabeçalhos de resposta e, possivelmente, um corpo da resposta.

Sobre o código de resposta e os cabeçalhos

Toda solicitação retornará um código de status HTTP que indica o sucesso da resposta. Para obter mais informações sobre códigos de resposta, confira a documentação do código de status de resposta HTTP do MDN.

Além disso, a resposta incluirá cabeçalhos que fornecem mais detalhes sobre a resposta. Cabeçalhos que começam com X- ou x- são personalizados para GitHub. Por exemplo, os cabeçalhos x-ratelimit-remaining e x-ratelimit-reset informam quantas solicitações você pode fazer em um período.

Para exibir o código de status e os cabeçalhos, use a opção --include ou --i ao enviar sua solicitação.

Por exemplo, esta solicitação obtém uma lista de issues no repositório the octocat/Spoon-Knife:

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include

E retorna um código de resposta e cabeçalhos semelhantes ao seguinte:

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, X-GitHub-OTP, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

Neste exemplo, o código de resposta é 200, o que indica uma solicitação bem-sucedida.

Quando você faz uma solicitação com Octokit.js, o método request retorna uma promessa. Se a solicitação tiver sido bem-sucedida, a promessa será resolvida para um objeto que inclui o código de status HTTP da resposta (status) e os cabeçalhos de resposta (headers). Se ocorrer um erro, a promessa será resolvida para um objeto que inclui o código de status HTTP da resposta (status) e os cabeçalhos de resposta (response.headers).

Você pode usar um bloco try/catch para capturar eventuais erros que ocorrerem. Por exemplo, se a solicitação no script a seguir for bem-sucedida, o script vai registrar o código de status e o valor do cabeçalho x-ratelimit-remaining. Se a solicitação não tiver sido bem-sucedida, o script vai registrar o código de status, o valor do cabeçalho x-ratelimit-remaining e a mensagem de erro.

No exemplo a seguir, substitua REPO-OWNER pelo nome da conta proprietária do repositório e REPO-NAME pelo nome do repositório.

JavaScript
try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

Para exibir o código de status e os cabeçalhos, use a opção --include ou --i ao enviar sua solicitação.

Por exemplo, esta solicitação obtém uma lista de issues no repositório the octocat/Spoon-Knife:

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

E retorna um código de resposta e cabeçalhos semelhantes ao seguinte:

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Neste exemplo, o código de resposta é 200, o que indica uma solicitação bem-sucedida.

Sobre o corpo da resposta

Muitos pontos de extremidade devolverão um corpo da resposta. A menos que especificado de outra forma, o corpo da resposta está no formato JSON. Os campos em branco são incluídos como null em vez de serem omitidos. Todos os carimbo de data/hora são devolvidos no formato UTC, ISO 8601: YYYY-MM-DDTHH:MM:SSZ.

Ao contrário da API do GraphQL em que você especifica quais informações deseja, a API REST normalmente retorna mais informações do que você precisa. Se desejar, você pode analisar a resposta a fim de extrair informações específicas.

Por exemplo, você pode usar > a fim de redirecionar a resposta para um arquivo. No exemplo a seguir, substitua REPO-OWNER pelo nome da conta proprietária do repositório e REPO-NAME pelo nome do repositório.

Shell
gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

Em seguida, você pode usar o jq para obter o título e a ID de autor de cada problema:

Shell
jq '.[] | {title: .title, authorID: .user.id}' data.json

Os dois comandos anteriores retornam algo como:

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Para obter mais informações sobre o jq, confira a documentação do jq.

Por exemplo, você pode obter o título e a ID do autor de cada problema. No exemplo a seguir, substitua REPO-OWNER pelo nome da conta proprietária do repositório e REPO-NAME pelo nome do repositório.

JavaScript
try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

Por exemplo, você pode usar > a fim de redirecionar a resposta para um arquivo. No exemplo a seguir, substitua REPO-OWNER pelo nome da conta proprietária do repositório e REPO-NAME pelo nome do repositório.

Shell
curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

Em seguida, você pode usar o jq para obter o título e a ID de autor de cada problema:

Shell
jq '.[] | {title: .title, authorID: .user.id}' data.json

Os dois comandos anteriores retornam algo como:

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Para obter mais informações sobre o jq, confira a documentação do jq.

Declarações detalhadas vs. resumidas

Uma resposta pode incluir todos os atributos de um recurso ou apenas um subconjunto de atributos, dependendo de você efetuar fetch de um recurso individual ou de uma lista de recursos.

  • Quando você efetuar fetch de um recurso individual, como um repositório específico, a resposta normalmente incluirá todos os atributos desse recurso. Esta é a representação "detalhada" do recurso.
  • Quando você efetuar fetch de uma lista de recursos, como uma lista de vários repositórios, a resposta incluirá apenas um subconjunto dos atributos para cada recurso. Esta é a representação "resumo" do recurso.

Observe que às vezes a autorização influencia a quantidade de detalhes incluídos em uma declaração.

A razão para isso é que alguns atributos são computacionalmente caros para a API fornecer, portanto, o GitHub exclui esses atributos da declaração resumida. Para obter esses atributos, você pode efetuar fetch da declaração detalhada.

A documentação fornece um exemplo de resposta para cada método da API. A resposta de exemplo ilustra todos os atributos que retornados por esse método.

Hipermídia

Todos os recursos podem ter uma ou mais propriedades *_url vinculando outros recursos. Estes tem o objetivo de fornecer URLs explícitas para que os clientes API apropriados não precisem construir URLs por conta própria. É altamente recomendável que os clientes da API os utilizem. Fazer isso tornará as futuras atualizações da API mais fáceis para os desenvolvedores. Espera-se que todas as URLs sejam modelos de URI RFC 6570 adequados.

Em seguida, você pode expandir esses modelos usando algo como ogem uri_template:

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

Próximas etapas

Este artigo demonstrou como listar e criar problemas em um repositório. Para obter mais práticas, tente comentar um problema, editar o título de um problema ou fechar um problema. Para obter mais informações, consulte o ponto de extremidade "Criar um comentário sobre o problema" e o ponto de extremidade "Atualizar um problema".

Para obter mais informações sobre outros pontos de extremidade que você pode usar, confira a documentação de referência de REST.