GitHub Pages is an easy, free way to make data available through an API.
What is GitHub Pages?
Any repo, user and organization on GitHub can have its own static website hosted by GitHub for free.
Many projects use it to host documentation websites but it can host any kind of content. Instead of hosting html, you can host JSON files.
- Go to the homepage of a repo you have admin access to
- Go to the “Settings” tab
- Scroll down to the “GitHub Pages” section
- Set “Source” to “master branch”
Wait a few seconds and then go to
https://<your github username>.github.io/<repo name>. Any files on the master branch in the repo are now served at that url.
GitHub graciously includes a wildcarded CORS header in the responses.
This is a big win because now any webpage can pull data directly from the API. No backend servers are needed.
Url and routes
The “base” url is made from your GitHub username (or organization name) and the repo name:
https://<username or organziation name>.github.io/<repo name>
Any url path after that is determined by directory structure of the repo.
A repo called “restaurant” with this directory structure
will have these routes
This kind of API is best suited for datasets that are read-only and mostly static.
The API is updated by
git push so highly dynamic data like stock prices would be difficult. Routes that appear to have ids in them are really just directories or files, so all of the data must be known ahead of time.
When a non-existent route is accessed, GitHub serves
404.html, if it exists at the root of the repo. Otherwise it serves a default 404 page. Sending html is not ideal for a JSON API but the response status code is probably the most important thing for clients, and that is set correctly.
I make my
404.html look like
Maybe that will help a confused developer figure out what they’re doing wrong.
A really basic browser client for an API like this could be