This project has a visual representation available on my Portfolio.
https://portfolio.owenthe.dev/snow-day-api
This project is describing the backend API for the Snow Day Predictor that I run. If you want to instead see project details about the frontend for the predictor, please click here.
The Snow Day API is a project that I’ve made over the course of a year to serve as the backend for the Snow Day Predictor, Dashboard, and SMS Service. Originally designed to control the SMS functions of the predictor, I built it up to also control the Snow Day Dashboard.
The Snow Day API got its start when I wanted to text out my snow day predictions during the 2018-2019 season. After some research, I came to the realization that I’d have to build some sort of API to handle the texts & registration for the system.
When development started, building an API was completely foreign to me. However, with trial and error, I was able to build a basic system using Python, Flask, and Twilio’s Python libraries (the SMS Service uses Twilio for sending the texts) in the course of a night.
After the first night, I started to work on the API being able to pick up more types of errors. Error catching is especially important when the user signs up for the service, so I coded in a ton of checks for landlines, messages not being delivered, user blocks, etc. In just the signup endpoint alone, there’s about 20 different error codes that the API can return.
The Snow Day API was looking pretty good, and had some sensible functionality in it for what it needed to do. It reliably ran the SMS aspects of the predictor for the remainder of the 2018-2019 season.
And then came the Snow Day Dashboard.
(if you’ve read the snow day dashboard page, this reads pretty similar to how that page reads. that’s because the dashboard & API were very much interconnected, so the API suffered due to the dashboard.)
See, the Snow Day Dashboard, in theory, is a really cool idea. The idea of being able to customize parts of the SMS experience is a cool idea, when it’s tightly integrated. Unfortunately, it was a case in extreme feature creep that I’m really not proud of. Read the (eventually coming) Snow Day Dashboard page for more information on why it didn’t work out.
Now, if I was smart, I would of served the dashboard from a separate Flask server. But no. I hosted it from a regular old server, meaning the API is relied on for every aspect of the dashboard!
Now, the actual session management code of the dashboard is pretty light, and there’s some sensible stuff going on with session timeouts, forcibly terminating sessions, you get the gist. However, I decided to be a nice guy and implement every method standalone. There’s a separate method for requesting a new auth code, there’s a method for validating session status and pre-auth session status. There’s 90 gazillion methods for the dashboard (and 90% aren’t even needed!!!) because feature creep!
Every page on the dashboard requires about 2-4 calls to the API to determine if a session is valid, load in content & settings, and other page-specific stuff. It’s extremely inefficient because I never thought to combine API methods for more efficiency. And, at the end of the day, the dashboard should have been hosted on a Flask server, because none of this would be needed.
I won’t go into the technical details of how the API works. Literally 80% of code is session checking, because I also had some sort of allergy to making a function (or wrapper in Flask’s case) that can do the checks.
The best part? Using APICurio Studio to write the API documentation, the spec file is bigger than the API. In the last revision of this post, I used this as an example of how efficient Python is. Now, I’m realizing that this was a massive red flag that feature creep took over the API & Dashboard. It’s also a red flag on how inefficient the API is, because your spec file should never be bigger than the API code itself!
Of course, this was my first API. I had no idea how to design an API properly. But, this is what I do. I look back at a project that didn’t work out, and find the mistakes that led to the demise. In the Snow Day API’s case, the mistakes that led to the demise was the dashboard, and how I never actually built it right.
In the end, all the work that I put in for the 2019-2020 season of the predictor was basically for nothing. There were two snow days, and literally nobody went on the dashboard (it’s a two-fold issue with the API & Dashboard since they’re pretty tightly integrated).
The lesson learned from the Snow Day API? Feature creep is real, and it ruins software. It’s a valuable lesson that I hope to keep in mind for a while now, and I’ll look back on the Snow Day API & Dashboard as the example.
Do I think I wasted my time on the API? Absolutely not. I gained a lot of technical knowledge on building an API with Flask, and I’m continuing to use Flask in projects today. The lessons I learned, however, from building the API were not a waste of time. I’m happy that I built up a project that had feature creep through the roof, and that I was able to realize why it failed a year later. That’s a good use of time, because I’ll know to keep an eye out on feature creep in the future.
Source code for the Snow Day API is available here: https://gitlab.com/o355/snowdayapi
