Static REST APIs on GitHub Pages

We already wrote about how central GitHub is to our work at Wiredcraft. We not only use it to collaborate and run our company, it also often is part of how we release applications. For example,’ very own documentation website (complete with a search) or this very website are GitHub Pages. Nothing unusual considering the momentum static generators have been gaining in the past couple years.

With that being said, we often take this concept a bit further. As we’ve said before, we very often build applications by coupling a static client and a REST API. What we haven’t talked much about is the fact that we often host both the client and the API on GitHub Pages. We use that approach for our clients at Wiredcraft (like GPE’s data hub) as well as our products.

The core idea is simply to store both the source of the client (usually an AngularJS app) and your raw data (often CSV files when we deal with small geo-datasets) in the master branch of your repository. We then proceed to compile this into a full blown static client and API “mock” in the gh-pages branch (using our beloved Here’s what it looks like:


The resulting API looks and behave like a regular REST API, save for .json appended to all the queries. We often end up using that approach for geo-data datasets, where you could have the following organization:

+- Algeria.json
+- Algeria/
|  |
|  +- Adrar.json
|  +- Chlef.json
|  +- Laghouat.json
|  +- ...
+- Angola.json
+- Angola/
+- Benin.json
+- Benin/
+- ...

There are multiple advantages to this approach, and we are actually applying some of it to something in the making sponsored by the Knight Foundation, but mostly it makes it very easy to build and ship projects. You immediately have a CI in place, and when it is time to deliver your project over to your client, you can simply migrate your entire repo over to their account. They not only get the source code, but also the production code (from the gh-pages branch), issues and documentation (wiki).

Also, it means you’re not hosting one more app, and we’re all about not making our lives more complicated than they already are.

We’ll soon be posting a tutorial on how to use to do this; in the meantime, don’t hesitate to come chat with us if you feel like asking us more details about it.

Juha Suomalainen
Engineering Director
Posted on August 06, 2014 in Technology

Share this post

Scan to open in WeChat

Stay tuned

Follow our newsletter or our WeChat account; every other week you'll receive news about what we're up to, our events and our insights on digital products, omnichannel, cross-border ecommerce or whatever the team fancies.

  • Add us on WeChat

  • Subscribe to our newsletter