Introdução à API REST

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

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

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', {})

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

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

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

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

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

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

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