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 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 os parâmetros de caminho que precisam ser especificados por você. Os parâmetros de caminho modificam o caminho do ponto de extremidade e são necessários em sua solicitação. Por exemplo, os parâmetros de caminho para o ponto de extremidade "Listar problemas do repositório" são {owner}
e {repo}
. Para usar esse caminho em sua solicitação de API, substitua {repo}
pelo nome do repositório no qual você deseja solicitar uma lista de problemas e substitua {owner}
pelo nome da conta proprietária do repositório.
Cabeçalhos
Os cabeçalhos fornecem informações adicionais sobre a solicitação e a resposta desejada. Veja a seguir alguns exemplos de cabeçalhos que você pode usar em suas solicitações para a API REST do GitHub. Para obter um exemplo de uma solicitação que usa cabeçalhos, consulte "Fazer uma solicitação".
Accept
A maioria dos pontos de extremidade da API REST do GitHub especifica que você deve transmitir um cabeçalho Accept
com um valor de application/vnd.github+json
. O valor do cabeçalho Accept
é um tipo de mídia. Para obter mais informações sobre os tipos de mídia, confira "Tipos de mídia".
X-GitHub-Api-Version
Você deve usar esse cabeçalho para especificar uma versão da API REST a ser usada para sua solicitação. Para 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, 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, 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.
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, 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.
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 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".
Note
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.
Warning
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. 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".
Warning
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
-
Para se autenticar no GitHub, execute o comando a seguir no terminal.
gh auth login
Você pode usar a opção
--scopes
para especificar os escopos desejados. Se você quiser autenticar com um token criado, poderá usar a opção--with-token
. Para obter mais informações, confira a documentaçãoauth login
da GitHub CLI. -
Selecione o local em que deseja se autenticar:
- Se você acessar o GitHub no GitHub.com, selecione GitHub.com.
- Se você acessar o GitHub em um domínio diferente, selecione Outro e depois insira o nome do host (por exemplo,
octocorp.ghe.com
).
-
Siga o restante das solicitações na tela.
O GitHub CLI armazena automaticamente suas credenciais do Git quando você escolhe HTTPS como protocolo preferencial para operações Git e responde "sim" ao prompt que pergunta se deseja efetuar a autenticação no Git com suas credenciais do GitHub. Isso pode ser útil porque permite que você use comandos Git como
git push
egit pull
sem a necessidade de configurar um gerenciador de credenciais distinto ou usar SSH.
3. Escolher um ponto de extremidade para sua solicitação
-
Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub para descobrir pontos de extremidade que você pode usar para interagir com o GitHub.
-
Identifique o método HTTP e o caminho do ponto de extremidade. Você vai enviá-los com sua solicitação. Para obter mais informações, consulte "Método HTTP" e "Caminho".
Por exemplo, o ponto de extremidade "Criar um problema" usa o método HTTP
POST
e o caminho/repos/{owner}/{repo}/issues
. -
Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes
{}
no caminho do ponto de extremidade. Substitua cada espaço reservado do parâmetro pelo valor desejado. Para obter mais informações, 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çalhoAccept
. Para transmitir vários tipos de mídia em um cabeçalhoAccept
, separe os tipos de mídia com uma vírgula:Accept: application/vnd.github+json,application/vnd.github.diff
. Para obter mais informações, confira "Accept
" e "Tipos de mídia."X-GitHub-Api-Version
: passe a versão da API em um cabeçalhoX-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 formatokey=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.
gh api --method GET /octocat \ --header 'Accept: application/vnd.github+json' \ --header "X-GitHub-Api-Version: 2022-11-28"
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.
gh api --method GET /events -F per_page=2 -F page=1 --header 'Accept: application/vnd.github+json' \
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.
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' \
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 exibir informações sobre a versão do
curl
, ocurl
está instalado. - Se você receber uma mensagem semelhante a
command not found: curl
, ocurl
não está instalado. Baixe e instale ocurl
. Para obter mais informações, confira a página de download do curl.
2. Escolher um ponto de extremidade para sua solicitação
-
Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub para descobrir pontos de extremidade que você pode usar para interagir com o GitHub.
-
Identifique o método HTTP e o caminho do ponto de extremidade. Você vai enviá-los com sua solicitação. Para obter mais informações, consulte "Método HTTP" e "Caminho".
Por exemplo, o ponto de extremidade "Criar um problema" usa o método HTTP
POST
e o caminho/repos/{owner}/{repo}/issues
. -
Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes
{}
no caminho do ponto de extremidade. Substitua cada espaço reservado do parâmetro pelo valor desejado. Para obter mais informações, 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, desta forma:https://api.github.com/PATH
. SubstituaPATH
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 formatoparameter_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
: passe o tipo de mídia em um cabeçalhoAccept
. Para transmitir vários tipos de mídia em um cabeçalhoAccept
, 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, confira "Accept
" e "Tipos de mídia."X-GitHub-Api-Version
: passe a versão da API em um cabeçalhoX-GitHub-Api-Version
. Para obter mais informações, confira "X-GitHub-Api-Version
".Authorization
: passe o token de autenticação em um cabeçalhoAuthorization
. Observe que, na maioria dos casos, você pode usarAuthorization: Bearer
ouAuthorization: token
para transmitir um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usarAuthorization: Bearer
. Para obter mais informações, confira "Autenticação". Para obter um exemplo de solicitação com um cabeçalhoAuthorization
, 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.
curl --request GET \ --url "https://api.github.com/octocat" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28"
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.
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
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.
Note
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".
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" }'
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 carregaroctokit
, confira o LEIA-ME do Octokit.js.
2. Escolher um ponto de extremidade para sua solicitação
-
Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a documentação da API REST do GitHub para descobrir pontos de extremidade que você pode usar para interagir com o GitHub.
-
Identifique o método HTTP e o caminho do ponto de extremidade. Você vai enviá-los com sua solicitação. Para obter mais informações, consulte "Método HTTP" e "Caminho".
Por exemplo, o ponto de extremidade "Criar um problema" usa o método HTTP
POST
e o caminho/repos/{owner}/{repo}/issues
. -
Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes
{}
no caminho do ponto de extremidade. Substitua cada espaço reservado do parâmetro pelo valor desejado. Para obter mais informações, 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
-
Importe
octokit
em seu script. Por exemplo,import { Octokit } from "octokit";
. Para outras maneiras de importaroctokit
, confira o LEIA-ME do Octokit.js. -
Crie uma instância de
Octokit
com seu token. SubstituaYOUR-TOKEN
pelo seu token.JavaScript const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
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ãoowner: "octocat"
erepo: "Spoon-Knife"
e os parâmetros de corpo sãotitle: "Created with the REST API"
ebody: "This is a test issue created by the REST API"
.Note
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", });
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çalhoAccept: application/vnd.github+json
. Para passar cabeçalhos adicionais ou um cabeçalhoAccept
diferente, adicione uma propriedadeheaders
ao objeto que é passado como o segundo argumento. O valor da propriedadeheaders
é 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 valortext/plain
e um cabeçalhoX-GitHub-Api-Version
com o valor de2022-11-28
.JavaScript await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2022-11-28", }, });
await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2022-11-28", }, });
- Envie o método HTTP e o caminho como o primeiro argumento do método
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-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, 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.
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}`) }
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-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, onde você especifica quais informações quer, 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.
gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 > data.json
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:
jq '.[] | {title: .title, authorID: .user.id}' data.json
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.
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}`) }
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.
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
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:
jq '.[] | {title: .title, authorID: .user.id}' data.json
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.