Introducción a la API REST

Para realizar una solicitud mediante JavaScript, puedes usar Octokit.js. Para obtener más información, vea «Scripting con la API de REST y JavaScript».

En primer lugar, crea una instancia de Octokit. y establece la dirección URL base en https://HOSTNAME/api/v3. Reemplaza [hostname] por el nombre de host de tu empresa.

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

A continuación, usa el método request para realizar solicitudes. Pasa el método HTTP y la ruta de acceso como primer argumento.

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

Para autenticarte con la biblioteca de Octokit.js, puedes pasar el token al crear una instancia de Octokit. Reemplaza YOUR-TOKEN por el token. Reemplaza [hostname] por el nombre de tu empresa.

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

También puedes usar la palabra clave run para ejecutar los scripts de JavaScript en los flujos de trabajo de GitHub Actions. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».

GitHub recomienda autenticarse con el GITHUB_TOKEN integrado en lugar de crear un token. Si esto no es posible, almacena el token como secreto y reemplaza GITHUB_TOKEN en el ejemplo siguiente por el nombre del secreto. Para obtener más información sobre GITHUB_TOKEN, consulta "Autenticación automática de tokens". Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions".

Observa el siguiente flujo de trabajo de ejemplo:

1. Comprueba el contenido del repositorio
2. Configura Node.js
3. Instala octokit
4. Almacena el valor de GITHUB_TOKEN como una variable de entorno denominada TOKEN y ejecuta .github/actions-scripts/use-the-api.mjs, que puede tener acceso a esa variable de entorno como process.env.TOKEN

Ejemplo de flujo de trabajo:

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@v4
        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

Script de JavaScript de ejemplo, con la ruta de acceso del archivo .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", {});

En lugar de almacenar el script en un archivo independiente y ejecutar el script desde el flujo de trabajo, puedes usar la acción actions/github-script para ejecutar un script. Para más información, consulta el archivo README actions/github-script.

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

La biblioteca de Octokit.js pasa automáticamente el encabezado Accept: application/vnd.github+json. Para pasar encabezados Accept adicionales o un encabezado diferente, agrega una propiedad headers al objeto que se pasa como segundo argumento al método request. El valor de la propiedad headers es un objeto con los nombres de encabezado como claves y valores de encabezado como valores. Por ejemplo, para enviar un encabezado content-type con un valor de text/plain:

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

Al realizar una solicitud con Octokit.js, todos los parámetros, incluidos los parámetros de ruta de acceso, se pasan en un objeto como segundo argumento al método request. Para obtener propuestas del repositorio octocat/Spoon-Knife, especifica owner como octocat y repo como Spoon-Knife.

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

Al realizar una solicitud con Octokit.js, todos los parámetros, incluidos los parámetros de ruta de acceso, se pasan en un objeto como segundo argumento al método request.

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

Al realizar una solicitud con Octokit.js, todos los parámetros, incluidos los parámetros de cuerpo, se pasan en un objeto como segundo argumento al 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",
});

Al realizar una solicitud con Octokit.js, el método request devuelve una promesa. Si la solicitud se realizó correctamente, la promesa se resuelve en un objeto que incluye el código de estado HTTP de la respuesta (status) y los encabezados de respuesta (headers). En caso de error, la promesa se resuelve en un objeto que incluye el código de estado HTTP de la respuesta (status) y los encabezados de respuesta (response.headers).

Puedes usar un bloque try/catch para detectar un error si se produce. Por ejemplo, si la solicitud del script siguiente se realiza correctamente, el script registrará el código de estado y el valor del encabezado x-ratelimit-remaining. Si la solicitud no se realizó correctamente, el script registrará el código de estado, el valor del encabezado x-ratelimit-remaining y el mensaje de error.

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 ejemplo, puedes obtener el título y el identificador de autor de cada propuesta:

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