Creating a Free Static API using a GitHub Repository
Tags: github, json, api, webdev
Published: 2022-04-25 02:04:11

Most APIs on the web are dynamic, meaning they're capable of generating, updating, and transforming content in response to requests. A static API is simply a collection of files (typically JSON) that are hosted online and can be accessed via HTTP request by an application. Unlike a dynamic API, a static API is unable to perform actions.


## Why use a Static API
Because dynamic APIs require you to run an application on a server, they can be expensive and difficult to maintain (especially at scale). Sometimes your application needs to access data via HTTP requests but doesn't need the other functionality an API can provide. If that's you, a static API can save you time and money, especially if you make use of a free static hosting solution, like GitHub.


## When to use a Static API
Consider using a static API if:
- You don't need to authenticate requests
- You only need to deliver pre-made content
- Actions don't need to be triggered by requests
- The content is not updated frequently


## How to use GitHub to Create Your Static API
To create a static API, all you need is to host JSON files somewhere online. Here's how you can do so for free using a GitHub repository:

### 1. **Create your JSON files.**
Create a JSON file containing the data you want each request to return. Name the files descriptively so you know what you're requesting in your code.

### 2. **Create a public GitHub repository.**
If you've never used GitHub, you'll need to create a free account. Here's the [documentation on how to create a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).

### 3. **Upload your JSON files to the repository.**
Here's [documentation on how to upload files](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository).

### 4. **Access your files via URL.**
The easiest way to do this is using GitHub RAW file URLs, HOWEVER, this is not best practice. In your final application, it's highly recommended that you use **GitHub Pages**, which will serve your files via CDN for better performance. I'll explain both methods.

#### Method 1: GitHub Pages (Recommended)
GitHub Pages is GitHub's free static hosting solution. Follow their [documentation on how to enable GitHub Pages in your repository](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site). Don't worry about giving your website a theme as the appearance of the site won't matter.

Once you've set up GitHub Pages in your repository, access your JSON files using this URL pattern: https://<user>.github.io/<repository>/<path>/<filename>

#### Method 2: GitHub RAW File URLs
This method doesn't require any additional setup. The URL to your raw file will look like this:
https://raw.githubusercontent.com/<username>/<repository>/<branch>/<path>/<filename>

_Example_: https://raw.githubusercontent.com/github/platform-samples/master/LICENSE.txt

In the above example, the user "github" has a repository named "platform-samples" with a branch named "master" that contains the file "LICENSE.txt" in the root directory.

If the file is in a folder in the repository, rather than the root directory, remember to include the path in the URL. _Example_: https://raw.githubusercontent.com/github/platform-samples/master/sql/metrics/actions-summary.sql

## Additional Notes
You can use GitHub raw file links to access files from any public GitHub repository, not just your own. If someone else has made data available for public use, this can be a great way to access it if they haven't made it available via an API (or if their API doesn't suit your needs).

**HOWEVER** The owner of the repository could modify or remove their files at any point. To avoid changes breaking your application, [fork the repository](https://docs.github.com/en/github-ae@latest/get-started/quickstart/fork-a-repo) and fetch the data from your fork instead.