Exploring Public APIs with GitHub's REST API

GitHub's REST API is a powerful tool for developers to interact with the extensive open-source community on the platform. With its comprehensive documentation and vast range of endpoints, the possibilities are endless. In this blog post, we'll cover how to get started with using the GitHub REST API, and provide some examples of how to use it in JavaScript.

Getting Started

Before we get started, we'll need to create a GitHub account and sign in. Once signed in, head over to the GitHub REST API documentation for version 3 at https://developer.github.com/v3/.

The documentation will provide you with an overview of the available endpoints, rate limits, authentication methods, and examples for each endpoint.

You can test any endpoint by using the "Try it out" feature available at the bottom of each endpoint's page. This feature allows you to enter required parameters and see the response before integrating it into your code.

Examples

Here are some examples of using the GitHub REST API in JavaScript:

How to Get a GitHub API Key (Personal Access Token)

Many GitHub REST API endpoints work with no key at all, but unauthenticated requests are capped at 60 per hour per IP. Authenticating with a personal access token (PAT) raises this to 5,000 requests per hour and unlocks private data and write actions.

To create a token:

1. Sign in to GitHub and open https://github.com/settings/tokens (Settings → Developer settings → Personal access tokens).
2. Choose "Fine-grained tokens" (recommended) and click "Generate new token".
3. Set an expiration, pick the repositories, and grant only the scopes/permissions you need.
4. Click "Generate token" and copy it immediately — it's shown only once.

Send the token in the Authorization header:

curl https://api.github.com/user/repos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.github+json"

The token is free. Treat it like a password: never commit it to a repository, and prefer fine-grained tokens so a leak exposes only the access you explicitly granted.

Example 1: Fetching user information

fetch('https://api.github.com/users/octocat')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error))

In this example, we use the fetch method to make a GET request to the /users/{username} endpoint. We then parse the JSON response and log it to the console.

Example 2: Creating a new repository

const requestData = {
  name: 'new-repo',
  description: 'This is a new repository',
  private: false
}

fetch('https://api.github.com/user/repos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer [access_token]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error))

In this example, we use the fetch method to make a POST request to the /user/repos endpoint to create a new repository. We pass in the required data in the body of the request as a JSON object. We also include an Authorization header with a valid access token. This ensures that the user creating the repository is authenticated as a valid user on the platform. Once the request is successful, we log the response to the console.

Example 3: Listing user's repositories

fetch('https://api.github.com/user/repos')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error))

In this example, we use the fetch method to make a GET request to the /user/repos endpoint to get a list of repositories for the authenticated user. Once we receive the response, we log it to the console.

Conclusion

GitHub's REST API is a fantastic tool for interacting with the open-source community. We covered the basics of how to get started with the API, and provided some examples of how to use it in JavaScript. Now that you're familiar with the API, it's time to start exploring and building your own integrations!