Getting started with the REST API

To make a request using JavaScript, you can use Octokit.js. For more information, see the Octokit.js README.

First, create an instance of Octokit. Set the base URL to http(s)://[hostname]/api/v3. Replace [hostname] with the name of your GitHub Enterprise Server instance.

const octokit = new Octokit({ 
  baseUrl: "http(s)://[hostname]/api/v3",
});

Then, use the request method to make requests. Pass the HTTP method and path as the first argument.

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

To authenticate with the Octokit.js library, you can pass your token when you create an instance of Octokit. Replace YOUR-TOKEN with your token. Replace [hostname] with the name of your GitHub Enterprise Server instance.

const octokit = new Octokit({ 
  baseUrl: "http(s)://[hostname]/api/v3",
  auth: 'YOUR-TOKEN',
});

You can also use the run keyword to execute your JavaScript scripts in your GitHub Actions workflows. For more information, see "Workflow syntax for GitHub Actions."

GitHub recommends that you authenticate with the built-in GITHUB_TOKEN instead of creating a token. If this is not possible, store your token as a secret and replace GITHUB_TOKEN in the example below with the name of your secret. For more information about GITHUB_TOKEN, see "Automatic token authentication." For more information about secrets, see "Encrypted secrets."

The following example workflow:

1. Checks out the repository content
2. Sets up Node.js
3. Installs octokit
4. Stores the value of GITHUB_TOKEN as an environment variable called TOKEN and runs .github/actions-scripts/use-the-api.mjs, which can access that environment variable as process.env.TOKEN

Example workflow:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '16.15.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

Example JavaScript script, with the file path .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://[hostname]/api/v3",
  auth: process.env.TOKEN,
});

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

Instead of storing your script in a separate file and executing the script from your workflow, you can use the actions/github-script action to run a script. For more information, see the actions/github-script README.

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

The Octokit.js library automatically passes the Accept: application/vnd.github+json header. To pass additional headers or a different Accept header, add a headers property to the object that is passed as a second argument to the request method. The value of the headers property is an object with the header names as keys and header values as values. For example, to send a content-type header with a value of text/plain:

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

When you make a request with Octokit.js, all parameters, including path parameters, are passed in an object as the second argument to the request method. To get issues from the octocat/Spoon-Knife repository, specify owner as octocat and repo as Spoon-Knife.

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

When you make a request with Octokit.js, all parameters, including query parameters, are passed in an object as the second argument to the request method.

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

When you make a request with Octokit.js, all parameters, including body parameters, are passed in an object as the second argument to the request method.

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

When you make a request with Octokit.js, the request method returns a promise. If the request was successful, the promise resolves to an object that includes the HTTP status code of the response (status) and the response headers (headers). If an error occurs, the promise resolves to an object that includes the HTTP status code of the response (status) and the response headers (response.headers).

You can use a try/catch block to catch an error if it occurs. For example, if the request in the following script is successful, the script will log the status code and the value of the x-ratelimit-remaining header. If the request was not successful, the script will log the status code, the value of the x-ratelimit-remaining header, and the error message.

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

For example, you can get the title and author ID of each issue:

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