Skip to main content

Atualmente o GitHub AE está em versão limitada.

Introdução à API REST

Saiba como usar a API REST do GitHub.

Sobre a API REST do GitHub

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

Ao fazer uma solicitação à API REST, você especificará um método HTTP e um caminho. Além disso, você também pode especificar cabeçalhos de solicitação e parâmetros de caminho, consulta ou corpo. A API retornará o código de status de resposta, os cabeçalhos de resposta e, potencialmente, um corpo de resposta.

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

Para obter mais informações sobre as APIs do GitHub, confira "Comparando a API REST do GitHub e a API GraphQL".

Como fazer uma solicitação

Para fazer uma solicitação, primeiro localize o método HTTP e o caminho da operação que deseja usar. Por exemplo, a operação "Obter Octocat" usa o método GET e o caminho /octocat. Para ver a documentação de referência completa dessa operação, confira "Meta".

Observação: você deve instalar a GitHub CLI para usar os comandos nos exemplos da GitHub CLI. Para obter instruções de instalação, confira o repositório da GitHub CLI.

Se ainda não estiver autenticado na GitHub CLI, você deverá usar o subcomando gh auth login para autenticar antes de fazer solicitações. Para obter mais informações, confira "Autenticação".

Para fazer uma solicitação usando a GitHub CLI, adote o subcomando api juntamente com o caminho. Use o sinalizador --method ou -X para especificar o método.

gh api /octocat --method GET

Observação: você deve instalar e importar octokit para usar a biblioteca Octokit.js empregada nos exemplos do JavaScript. Para obter mais informações, confira o arquivo LEIA-ME do Octokit.js.

Para fazer uma solicitação usando JavaScript, você pode usar o Octokit.js. Para obter mais informações, confira "Scripts com a API REST e o JavaScript".

Primeiro, crie uma instância de Octokit. Defina a URL de base como https://HOSTNAME/api/v3. Substitua [hostname] pelo nome da sua empresa.

const octokit = new Octokit({ 
  baseUrl: "https://HOSTNAME/api/v3",
});

Em seguida, use o método request para fazer solicitações. Passe o método HTTP e o caminho como o primeiro argumento.

await octokit.request("GET /octocat", {});

Acrescente a URL base da API REST do GitHub, https://HOSTNAME/api/v3, ao caminho para obter a URL completa: https://HOSTNAME/api/v3/octocat. Substitua [hostname] pelo nome da sua empresa.

Use o comando curl na sua linha de comando. Use o sinalizador --request ou -X, seguido pelo método HTTP. Use o sinalizador --url seguido pela URL completa.

curl --request GET \
--url "https://api.github.com/octocat"

Observação: se você receber uma mensagem semelhante a "comando não encontrado: curl", talvez seja necessário baixar e instalar o curl. Para obter mais informações, confira a página de download do projeto curl.

Continue lendo para saber como autenticar, enviar parâmetros e usar a resposta.

Autenticação

Muitas operações exigem autenticação ou retornam informações adicionais se você estiver autenticado. Além disso, você pode fazer mais solicitações por hora quando está autenticado.

Embora algumas operações de API REST estejam acessíveis sem autenticação, você precisa se autenticar na GitHub CLI para usar o subcomandoapi.

Sobre os tokens

Você pode autenticar sua solicitação adicionando um token.

Se quiser usar a API REST do GitHub para uso pessoal, crie um personal access token. As operações da API REST usadas neste artigo exigem o escopo repo para personal access tokens. Outras operações podem exigir escopos diferentes. Para obter mais informações sobre como criar um personal access token, confira "Gerenciar seus tokens de acesso pessoal".

Se você quiser usar a API em nome de uma organização ou de outro usuário, a GitHub recomenda que você use um GitHub App. Se uma operação estiver disponível para um GitHub Apps, a documentação de referência de REST para essa operação dirá "Funciona com Aplicativos do GitHub". As operações da API REST usadas neste artigo exigem permissões de leitura e gravação issues para GitHub Apps. Outras operações podem exigir permissões diferentes. Para obter mais informações, confira "Registrar um Aplicativo GitHub", "Sobre a autenticação com um GitHub App" e "Autenticação com um aplicativo GitHub em nome de um usuário".

Se você quiser usar a API em um fluxo de trabalho de GitHub Actions, a GitHub recomenda que você se autentique com o GITHUB_TOKEN interno, em vez de criar um token. Você pode conceder permissões à GITHUB_TOKEN com a chave permissions. Para obter mais informações, confira "Autenticação automática de token".

Para ter mais informações sobre as práticas recomendadas que você pode usar para manter seus tokens seguros, confira "Manter suas credenciais de API seguras".

Exemplo de autenticação

Com a GitHub CLI, você não precisa criar um token de acesso com antecedência. Use o subcomando auth login para se autenticar na GitHub CLI:

gh auth login

Você pode usar o sinalizador --scopes para especificar quais escopos deseja. Se você quiser autenticar com um token criado, poderá usar o sinalizador --with-token. Para obter mais informações, confira a documentação da GitHub CLIauth login.

Aviso: trate seu token de acesso como uma senha.

Para manter seu token seguro, você pode armazená-lo como um segredo e executar seu script por meio de GitHub Actions. Para obter mais informações, confira "Usar segredos em ações do GitHub".

Se essas opções não forem possíveis, considere usar outro serviço de CLI para armazenar seu token com segurança.

Para se autenticar com a biblioteca Octokit.js, você pode passar seu token ao criar uma instância de Octokit. Substitua YOUR-TOKEN pelo token. Substitua [hostname] pelo nome da sua empresa.

const octokit = new Octokit({ 
  baseUrl: "https://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

Aviso: trate seu token de acesso como uma senha.

Para ajudar a manter sua conta segura, você pode usar a GitHub CLI em vez dos comandos curl. A GitHub CLI cuidará da autenticação para você. Para obter mais informações, confira a versão da GitHub CLI desta página.

Se essas opções não forem possíveis, considere usar outro serviço de CLI para armazenar seu token com segurança.

Com os comandos curl, você enviará um cabeçalho Authorization com seu token. Substitua YOUR-TOKEN pelo seu token:

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

Observação: Na maioria dos casos, você pode usar Authorization: Bearer ou Authorization: token a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer.

Exemplo de autenticação para GitHub Actions

Você também pode usar a palavra-chave run para executar comandos da GitHub CLI em seus fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Em vez de usar o comando gh auth login, passe seu token como uma variável de ambiente chamada GH_TOKEN. O GitHub recomenda que você se autentique com o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /octocat

Você também pode usar a palavra-chave run para executar seus scripts do JavaScript nos fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

O GitHub recomenda que você se autentique com o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

O seguinte exemplo de fluxo de trabalho:

  1. Verifica o conteúdo do repositório
  2. Configura o Node.js
  3. Instala octokit
  4. Armazena o valor de GITHUB_TOKEN como uma variável de ambiente chamada de TOKEN e executa .github/actions-scripts/use-the-api.mjs, que pode acessar essa variável de ambiente como process.env.TOKEN

Fluxo de trabalho de exemplo:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node .github/actions-scripts/use-the-api.mjs

Exemplo de script do JavaScript, com o caminho do arquivo .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "https://HOSTNAME/api/v3",
  auth: process.env.TOKEN,
});

await octokit.request("GET /octocat", {});

Em vez de armazenar o script em um arquivo separado e executar o script do seu fluxo de trabalho, você pode usar a ação actions/github-script para executar um script. Para obter mais informações, confira o arquivo actions/github-script README.

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

Você também pode usar a palavra-chave run para executar comandos curl em seus fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

O GitHub recomenda que você se autentique com o GITHUB_TOKEN interno em vez de criar um token. Se isso não for possível, armazene o token como um segredo e substitua GITHUB_TOKEN no exemplo abaixo pelo nome do seu segredo. Para obter mais informações sobre GITHUB_TOKEN, confira "Autenticação automática de token". Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/octocat" \
          --header "Authorization: Bearer $GH_TOKEN"

Uso de cabeçalhos

A maioria das operações especifica que você deve passar um cabeçalho Accept com o valor application/vnd.github+json. Outras operações podem especificar que você deve enviar um cabeçalho Accept diferente ou cabeçalhos adicionais.

Para enviar um cabeçalho com a GitHub CLI, use o sinalizador --header ou -H, seguido do cabeçalho no formato key: value.

gh api --header 'Accept: application/vnd.github+json' --method GET /octocat

A biblioteca de Octokit.js 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 um segundo argumento para o método request. O valor da propriedade headers é um objeto com os nomes de cabeçalho como chaves e valores de cabeçalho como valores. Por exemplo, para enviar um cabeçalho content-type com o valor text/plain:

await octokit.request("GET /octocat", {
  headers: {
    "content-type": "text/plain",
  },
});

Para enviar um cabeçalho em um comando curl, use o sinalizador --header ou -H seguido pelo cabeçalho no formato key: value.

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

Como usar parâmetros de caminho

Os parâmetros de caminho modificam o caminho da operação. Por exemplo, o caminho "Listar problemas de repositório" é /repos/{owner}/{repo}/issues. As chaves {} denotam parâmetros de caminho que você precisa especificar. Nesse caso, você deve especificar o proprietário e o nome do repositório. Para ver a documentação de referência completa dessa operação, confira "Problemas".

Observação: para que esse comando funcione na sua empresa, substitua octocat/Spoon-Knife por um repositório pertencente à sua empresa. Caso contrário, execute novamente o comando gh auth login para se autenticar no GitHub.com em vez de sua empresa.

Para obter problemas do repositório octocat/Spoon-Knife, substitua {owner} por octocat e {repo} por Spoon-Knife.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues

Observação: para que esse exemplo funcione na sua empresa, substitua octocat/Spoon-Knife por um repositório pertencente à sua empresa. Caso contrário, crie uma instância Octokit e não especifique baseURL.

Quando você faz uma solicitação com Octokit.js, todos os parâmetros, incluindo parâmetros de caminho, são passados em um objeto como o segundo argumento para o método request. Para obter problemas do repositório octocat/Spoon-Knife, especifique owner como octocat e repo como Spoon-Knife.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife"
});

Para obter problemas do repositório octocat/Spoon-Knife, substitua {owner} por octocat e {repo} por Spoon-Knife. Para criar o caminho completo, prepare a URL de base para a API REST do GitHub, https://api.github.com: https://api.github.com/repos/octocat/Spoon-Knife/issues.

Observação: se você quiser usar sua empresa em vez do GitHub.com, use https://HOSTNAME/api/v3 em vez de https://api.github.com e substitua [hostname] pelo nome da sua empresa. Substitua octocat/Spoon-Knife por um repositório pertencente à sua empresa.

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

A operação retorna uma lista de problemas e dados sobre cada problema. Para obter mais informações sobre como usar a resposta, confira a seção "Como usar a resposta".

Como usar parâmetros de consulta

Os parâmetros de consulta permitem controlar quais dados são retornados para uma solicitação. Por exemplo, um parâmetro de consulta pode permitir que você especifique quantos itens são retornados quando a resposta é paginada.

Por padrão, a operação "Listar problemas de repositório" retorna trinta problemas, classificados em ordem decrescente pela data em que foram criados. Você pode usar o parâmetro per_page para retornar dois problemas em vez de 30. Você pode usar o sort parâmetro para classificar os problemas pela data em que foram atualizados pela última vez, em vez da data em que foram criados. Você pode usar o parâmetro direction para classificar os resultados em ordem crescente em vez de ordem decrescente.

Para a GitHub CLI, use o sinalizador -F para passar um parâmetro numérico, booliano ou nulo. Use -f para passar parâmetros de cadeia de caracteres.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc

Algumas operações 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.

Para usar a GitHub CLI com parâmetros de consulta que são matrizes, você deve usar a GitHub CLI versão 2.31.0 ou superior. Para obter instruções de upgrade, confira o repositório da GitHub CLI.

Quando você faz uma solicitação com Octokit.js, todos os parâmetros, incluindo parâmetros de consulta, são passados em um objeto como o segundo argumento para o método request.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
  sort: "updated",
  direction: "asc",
});

No caso de comandos curl, adicione um ? ao final do caminho e, em seguida, anexe o nome e o valor do parâmetro de consulta no formato parameter_name=value. Separe vários parâmetros de consulta com &.

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

Algumas operações 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 ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID.

A operação retorna uma lista de problemas e dados sobre cada problema. Para obter mais informações sobre como usar a resposta, confira a seção "Como usar a resposta".

Como usar parâmetros do corpo

Os parâmetros do corpo permitem que você passe dados adicionais para a API. Por exemplo, a operação "Criar um problema" exige que você especifique um título para o novo problema. Ele também permite que você especifique outras informações, como o texto a ser colocado no corpo do problema. Para ver a documentação de referência completa dessa operação, confira "Problemas".

A operação "Criar um problema" usa o mesmo caminho que a operação "Listar problemas do repositório" nos exemplos acima, mas usa o método POST em vez do método GET.

Para a GitHub CLI, use o sinalizador -F para passar um parâmetro numérico, booliano ou nulo. Use -f para passar parâmetros de cadeia de caracteres. Se o parâmetro for uma matriz, você deverá acrescentar [] ao nome do parâmetro.

Para usar a GitHub CLI com parâmetros de corpo que são matrizes, você deve usar a GitHub CLI versão 2.21.0 ou superior. Para obter instruções de upgrade, confira o repositório da GitHub CLI.

gh api --header 'Accept: application/vnd.github+json' --method POST /repos/octocat/Spoon-Knife/issues -f title="Created with the REST API" -f body="This is a test issue created by the REST API" -f "labels[]=bug"

Quando você faz uma solicitação com Octokit.js, todos os parâmetros, incluindo parâmetros de corpo, são passados em um objeto como o segundo argumento para o método request.

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",
});

No caso de comandos curl, use o sinalizador --data para passar os parâmetros do corpo em um objeto JSON.

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

A operação cria um problema e retorna dados sobre o novo problema. Na resposta, localize o html_url do problema e navegue até o problema no navegador. Para obter mais informações sobre como usar a resposta, confira a seção "Como usar a resposta".

Como usar a 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 o sinalizador --include ou --i ao enviar sua solicitação.

Por exemplo, esta solicitação:

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

retorna o código de resposta e os cabeçalhos como:

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.

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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 o sinalizador --include ou --i ao enviar sua solicitação.

Por exemplo, esta solicitação:

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

retorna o código de resposta e os cabeçalhos como:

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

Muitas operações retornarão um corpo de resposta. A menos que especificado de outra forma, o corpo da resposta está no formato JSON. Por exemplo, essa solicitação retorna uma lista de problemas com os dados sobre cada problema:

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
});
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"

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:

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/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:

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:

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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:

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" > data.json

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

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.

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 sobre essas operações, confira "Problemas" e "Problemas".

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