In honor of Earth Day, I thought I’d try something a little different for my newest API. This API is a calendar of environmental holidays, paired with a React app which displays them in chronological order. The result is a handy little app I call EcoDays. The code, which is MIT-licensed as always, is available at https://github.com/shaisachs/ecodays.

My goal for this project was to play around with hosting an API on Github Pages, and also to get my feet wet with React. Github Pages is an excellent hosting environment, because it’s free and fast, and tightly integrated with the Github source control system I’m already using anyway. The catch is that it’s also all static, so it’s not really suitable to a wide range of APIs. But if you’re mostly looking to provide a simple set of content by API, it can be a wonderful resource.

The API in this project is quite simple: it’s all available at GET https://shaisachs.com/ecodays/api.json, and it gives you a list of a few dozen holidays, including names, websites, and dates. Many of these holidays aren’t fixed to a particular date of the year, but rather a position within the month - for example, Earth Hour occurs on the last Saturday of March. To accommodate these holidays, I used the iCalendar Recurrence Rule format (rrule) for storing dates.

I briefly gave some thought to making the API answer the sort of question that the site is intended for: for a given holiday X and a date range Y - Z, when (if ever) will X occur between Y and Z? Or perhaps less arithmetically, what’s the next concrete occurrence of Earth Hour? It’s pretty easy to answer this question with the benefit of a server-side script which serves up the API - there are dozens of rrule libraries in any programming language you care to choose. But with Github Pages, your entire site is pre-baked into static files before it’s served to a visitor, so the best you can do is to calculate this question over a fixed time range (let’s say a year). In order to keep the site up to date, you’d have to do something horrendous like deploying the site every day. Instead I chose to put the burden of answering this problem on the client - who, unlike the server, has the benefit of loading up an rrule library.

In this case the client was a React script I cobbled together. It’s a fairly bare-bones, you might even say downright ugly, little app. All it does is fetch the list of holidays, load up the rrule library, and throws some very trivial formatting around the whole mess. I used the gh-pages package to build and deploy the app to Github Pages, and for the most part it was not too difficult; the main trick was just understanding how the package works, but I got that sorted out reasonably well. (The answer is, it builds the React app in your master branch’s src/ directory, then cobbles it together with static apps in your master branch’s public/ directory, and pushes the whole mess into your gh-pages branch. Consequently, it’s important to set your Github Pages settings to publish out of your gh-pages branch.) Undoubtedly the app can and should be cleaned up: for example by moving most of the mess around rendering holidays in the global component into a child Holiday component.

This project was a lot of fun to cobble together. The API is straightforward and, via Github pull requests and issues, readily crowdsourced. The hosting is free and easy, which is a nice little bonus. And the result is a fast little widget which, I’d like to hope, will get some good usage by environmentalists everywhere!