# Início Rápido da API REST GitHub

Saiba como começar a usar a GitHub API REST.

## Introdução

Este artigo descreve como começar rapidamente com a GitHub API REST usando GitHub CLI, `curl`ou JavaScript. Para ver um guia mais detalhado, confira [Introdução à API REST](/pt/rest/guides/getting-started-with-the-rest-api).

<div class="ghd-tool cli">

## Como usar GitHub CLI na linha de comando

GitHub CLI é a maneira mais fácil de usar a GitHub API REST da linha de comando.

1. Instale a GitHub CLI no macOS, no Windows ou no Linux. Para obter instruções de instalação, confira [Instalação](https://github.com/cli/cli?ref_product=cli\&ref_type=engagement\&ref_style=text#installation) no repositório do GitHub CLI.

2. Para se autenticar no GitHub, execute o comando a seguir no terminal.

   ```shell
   gh auth login
   ```

3. 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`).

4. Siga o restante das solicitações na tela.

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

5. Faça uma solicitação usando o GitHub CLI`api` subcomando, seguido pelo caminho. Use o sinalizador `--method` ou `-X` para especificar o método. Para obter mais informações, consulte a [GitHub CLI`api` documentação](https://cli.github.com/manual/gh_api).

   Este exemplo faz uma solicitação para o endpoint "Obter Octocat", que usa o método `GET` e o caminho `/octocat`. Para ver a documentação completa de referência desse ponto de extremidade, confira [Pontos de extremidade da API REST para metadados](/pt/rest/meta/meta#get-octocat).

   ```shell copy
   gh api /octocat --method GET
   ```

## Usando GitHub CLI em GitHub Actions

Você também pode usar GitHub CLI em seus GitHub Actions fluxos de trabalho. Para saber mais, confira [Usando GitHub CLI em fluxos de trabalho](/pt/actions/using-workflows/using-github-cli-in-workflows).

### Autenticação com um token de acesso

Em vez de usar o comando `gh auth login`, passe um token de acesso como uma variável de ambiente chamada `GH_TOKEN`.
GitHub recomenda que você use o `GITHUB_TOKEN` integrado 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 [Usar GITHUB\_TOKEN para autenticação em fluxos de trabalho](/pt/actions/security-guides/automatic-token-authentication). Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).

O fluxo de trabalho de exemplo a seguir usa o ponto de extremidade [Listar problemas de repositório](/pt/rest/issues/issues#list-repository-issues) e solicita uma lista de problemas  que `octocat/Spoon-Knife`você especificar.

```yaml copy
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
```

### Autenticando com um GitHub App

Se você estiver autenticando com um GitHub App, poderá criar um token de acesso de instalação em seu fluxo de trabalho:

1. Armazene o ID do cliente de GitHub App como uma variável de configuração. No exemplo a seguir, substitua `APP_CLIENT_ID` pelo nome da variável de configuração. Você pode encontrar sua ID do cliente na página de configurações do aplicativo ou por meio da API. Para saber mais, confira [Pontos de extremidade da API REST para o GitHub Apps](/pt/rest/apps/apps#get-an-app). Para saber mais sobre variáveis de configuração, confira [Armazenar informações em variáveis](/pt/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo `-----BEGIN RSA PRIVATE KEY-----` e `-----END RSA PRIVATE KEY-----`). No exemplo a seguir, substitua `APP_PRIVATE_KEY` pelo nome do segredo. Para saber mais, confira [Gerenciando chaves privadas para aplicativos GitHub](/pt/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).
3. Adicione uma etapa para gerar um token e use esse token em vez de `GITHUB_TOKEN`. Observe que esse token vai expirar após 60 minutos.
   Por exemplo:

   ```yaml copy
   on:
     workflow_dispatch:
   jobs:
     track_pr:
       runs-on: ubuntu-latest
       steps:
         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v3
           with:
             client-id: ${{ vars.APP_CLIENT_ID }}
             private-key: ${{ secrets.APP_PRIVATE_KEY }}
         - name: Use API
           env:
             GH_TOKEN: ${{ steps.generate-token.outputs.token }}
           run: |
             gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
   ```

</div>

<div class="ghd-tool javascript">

## Como usar Octokit.js

Você pode usar Octokit.js para interagir com a GitHub API REST em seus scripts JavaScript. Para obter mais informações, confira [Scripts com a API REST e o JavaScript](/pt/rest/guides/scripting-with-the-rest-api-and-javascript).

1. Crie um token de acesso. Por exemplo, crie um personal access token ou um GitHub App token de acesso do usuário. Você usará esse token para autenticar sua solicitação, então deve conceder a ele todos os escopos ou permissões necessários para acessar esse endpoint. Para obter mais informações, consulte [Autenticação na API REST](/pt/rest/overview/authenticating-to-the-rest-api) ou [Identificando e autorizando usuários para aplicativos do GitHub](/pt/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps).

   > \[!WARNING]
   > Trate o token de acesso como faria com uma senha.
   >
   > Para manter seu token seguro, você pode armazenar seu token como segredo e executar seu script por meio de GitHub Actions. Para obter mais informações, consulte a seção [Usando Octokit.js.GitHub Actions](#using-octokitjs-in-github-actions)

   Você também pode armazenar seu token como um Codespaces segredo e executar seu script em Codespaces. Para obter mais informações, confira [Como gerenciar segredos criptografados para seus codespaces](/pt/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces).

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

2. Instale `octokit`. Por exemplo, `npm install octokit`. Para outras formas de instalar ou carregar `octokit`, consulte o [README do Octokit.js](https://github.com/octokit/octokit.js/#readme).

3. Importe `octokit` em seu script. Por exemplo, `import { Octokit } from "octokit";`. Para outras maneiras de importar `octokit`, confira o [README do Octokit.js](https://github.com/octokit/octokit.js/#readme).

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

   ```javascript copy
   const octokit = new Octokit({ 
     auth: 'YOUR-TOKEN'
   });
   ```

5. Use `octokit.request` para executar sua solicitação. Envie o método HTTP e o caminho como o primeiro argumento. Especifique quaisquer parâmetros de caminho, consulta e corpo em um objeto como o segundo argumento. Para obter mais informações sobre parâmetros, confira [Introdução à API REST](/pt/rest/guides/getting-started-with-the-rest-api#using-parameters).

   Por exemplo, na solicitação a seguir, o método HTTP é`GET`, o caminho é`/repos/{owner}/{repo}/issues`, e os parâmetros são`owner: "octocat"``repo: "Spoon-Knife"`

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

## Usando Octokit.js em GitHub Actions

Você também pode executar seus scripts JavaScript em seus GitHub Actions fluxos de trabalho. Para saber mais, confira [Sintaxe de fluxo de trabalho para o GitHub Actions](/pt/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun).

### Autenticação com um token de acesso

GitHub recomenda que você use o `GITHUB_TOKEN` integrado 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 [Usar GITHUB\_TOKEN para autenticação em fluxos de trabalho](/pt/actions/security-guides/automatic-token-authentication). Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).

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`

```yaml
on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v6

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

      - name: Install dependencies
        run: npm install octokit

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

Veja a seguir um exemplo de script JavaScript com o caminho `.github/actions-scripts/use-the-api.mjs`do arquivo.

```javascript
import { Octokit } from "octokit"

const octokit = new Octokit({ 
  auth: process.env.TOKEN
});

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

  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}`)
}
```

### Autenticando com um GitHub App

Se você estiver autenticando com um GitHub App, poderá criar um token de acesso de instalação em seu fluxo de trabalho:

1. Armazene o ID de cliente do seu GitHub App como uma variável de configuração. No exemplo a seguir, substitua `APP_CLIENT_ID` pelo nome da variável de configuração. Você pode encontrar sua ID do cliente na página de configurações do aplicativo ou por meio da API de Aplicativo. Para saber mais, confira [Pontos de extremidade da API REST para o GitHub Apps](/pt/rest/apps/apps#get-an-app). Para saber mais sobre variáveis de configuração, confira [Armazenar informações em variáveis](/pt/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo `-----BEGIN RSA PRIVATE KEY-----` e `-----END RSA PRIVATE KEY-----`). No exemplo a seguir, substitua `APP_PRIVATE_KEY` pelo nome do segredo. Para saber mais, confira [Gerenciando chaves privadas para aplicativos GitHub](/pt/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).
3. Adicione uma etapa para gerar um token e use esse token em vez de `GITHUB_TOKEN`. Observe que esse token vai expirar após 60 minutos. Por exemplo:

   ```yaml
   on:
     workflow_dispatch:
   jobs:
     use_api_via_script:
       runs-on: ubuntu-latest
       steps:
         - name: Check out repo content
           uses: actions/checkout@v6

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

         - name: Install dependencies
           run: npm install octokit

         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v3
           with:
             client-id: ${{ vars.APP_CLIENT_ID }}
             private-key: ${{ secrets.APP_PRIVATE_KEY }}

         - name: Run script
           run: |
             node .github/actions-scripts/use-the-api.mjs
           env:
             TOKEN: ${{ steps.generate-token.outputs.token }}

   ```

</div>

<div class="ghd-tool curl">

## Como usar `curl` na linha de comando

> \[!NOTE]
> Se você quiser fazer solicitações de API da linha de comando, GitHub recomenda que você use GitHub CLI, o que simplifica a autenticação e as solicitações. Para obter mais informações sobre como começar a usar a API GitHub CLIREST, consulte a GitHub CLI versão deste artigo.

1. Instale o `curl` caso ainda não o tenha feito em seu computador. Para verificar se o `curl` está instalado, execute `curl --version` na linha de comando. Se a saída fornecer informações sobre a versão do `curl`, isso significará que o `curl` está instalado. Se você receber uma mensagem semelhante a `command not found: curl`, será necessário baixar e instalar o `curl`. Para obter mais informações, confira a [página de download do projeto curl](https://curl.se/download.html).

2. Crie um token de acesso. Por exemplo, crie um personal access token ou um GitHub App token de acesso do usuário. Você usará esse token para autenticar sua solicitação, portanto, deve conceder a ele todos os escopos ou permissões necessários para acessar o endpoint. Para saber mais, confira [Autenticação na API REST](/pt/rest/overview/authenticating-to-the-rest-api).

   > \[!WARNING]
   > Trate o token de acesso como faria com uma senha.
   >
   > Para manter seu token seguro, você pode armazenar seu token como um Codespaces segredo e usar a linha de comando por meio Codespaces. Para obter mais informações, confira [Como gerenciar segredos criptografados para seus codespaces](/pt/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces).

   > Você pode usar GitHub CLI em vez de `curl`.
   > GitHub CLI cuidará da autenticação para você. Para obter mais informações, consulte a GitHub CLI versão 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.

3. Use o comando `curl` para fazer sua solicitação. Envie seu token em um `Authorization` cabeçalho. Substitua `YOUR-TOKEN` pelo seu token.

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

   > \[!NOTE]
   > 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`.

## Usando comandos `curl` em GitHub Actions

Você também pode usar os comandos `curl` nos seus fluxos de trabalho GitHub Actions.

### Autenticação com um token de acesso

GitHub recomenda que você use o `GITHUB_TOKEN` integrado 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 [Usar GITHUB\_TOKEN para autenticação em fluxos de trabalho](/pt/actions/security-guides/automatic-token-authentication). Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).

```yaml copy
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
          --header "Accept: application/vnd.github+json" \
          --header "Authorization: Bearer $GH_TOKEN"
```

### Autenticando com um GitHub App

Se você estiver autenticando com um GitHub App, poderá criar um token de acesso de instalação em seu fluxo de trabalho:

1. Armazene o ID do cliente do seu GitHub App como uma variável de configuração. No exemplo a seguir, substitua `APP_CLIENT_ID` pelo nome da variável de configuração. Você pode encontrar sua ID do cliente na página de configurações do aplicativo ou por meio da API de Aplicativo. Para saber mais, confira [Pontos de extremidade da API REST para o GitHub Apps](/pt/rest/apps/apps#get-an-app). Para saber mais sobre variáveis de configuração, confira [Armazenar informações em variáveis](/pt/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
2. Gerar uma chave privada para o seu aplicativo. Armazene o conteúdo do arquivo resultante como um segredo. (Armazene todo o conteúdo do arquivo, incluindo `-----BEGIN RSA PRIVATE KEY-----` e `-----END RSA PRIVATE KEY-----`). No exemplo a seguir, substitua `APP_PRIVATE_KEY` pelo nome do segredo. Para saber mais, confira [Gerenciando chaves privadas para aplicativos GitHub](/pt/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). Para saber mais sobre como armazenar segredos, confira [Usar segredos em ações do GitHub](/pt/actions/security-guides/encrypted-secrets).
3. Adicione uma etapa para gerar um token e use esse token em vez de `GITHUB_TOKEN`. Observe que esse token vai expirar após 60 minutos.
   Por exemplo:

   ```yaml copy
   on:
     workflow_dispatch:
   jobs:
     use_api:
       runs-on: ubuntu-latest
       steps:
         - name: Generate token
           id: generate-token
           uses: actions/create-github-app-token@v3
           with:
             client-id: ${{ vars.APP_CLIENT_ID }}
             private-key: ${{ secrets.APP_PRIVATE_KEY }}

         - name: Use API
           env:
             GH_TOKEN: ${{ steps.generate-token.outputs.token }}
           run: |
             curl --request GET \
             --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
             --header "Accept: application/vnd.github+json" \
             --header "Authorization: Bearer $GH_TOKEN"

   ```

</div>

## Próximas etapas

Para obter um guia mais detalhado, confira [Introdução à API REST](/pt/rest/guides/getting-started-with-the-rest-api).