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.
api
.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:
- Verifica o conteúdo do repositório
- Configura o Node.js
- Instala
octokit
- Armazena o valor de
GITHUB_TOKEN
como uma variável de ambiente chamada deTOKEN
e executa.github/actions-scripts/use-the-api.mjs
, que pode acessar essa variável de ambiente comoprocess.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.