OnlineOrNot Diaries 18
Max Rozen (@RozenMD) / January 15, 2024
It's a rainy Monday morning here in Toulouse, time for another diary.
Table of contents
2023, what a year
Over the Christmas/New Year break I wrote a year-in-review article for how all of my projects went in 2023. The gist of it was: I focused on only OnlineOrNot for a whole year, and the business grew twice as fast as I expected, and the article seemed to resonate with a lot of people, getting about 20k unique views.
In that article I promised a proper year in review article for just OnlineOrNot on its birthday (February 25). I'm pretty thankful I've been writing these diaries on a regular basis since OnlineOrNot's last birthday, here's hoping it makes it easier to remember just what I did over a whole year.
A fresh start, more shop cleaning
As I mention in my last diary, I ended the year feeling inspired for 2024, ready to improve OnlineOrNot and the Status Pages feature to a point where bigger tech companies (I'm thinking a few hundred employees) feel more comfortable using it.
A big part of that is cleaning up the API and the tooling around it, and building new API endpoints. I originally shipped OnlineOrNot's API solely as a means of building a CLI. The docs were hand-written, and lovingly placed alongside my other hand-written docs. Side note: I'm starting to notice this is a recurring theme - I'll build something quickly, and have to come back to clean it up later. That's probably preferable to taking months to ship anything.
Unfortunately, this made updating the API a bit of a pain in the ass. Updating the API meant first writing code, and remembering to context-switch into "content-mode" and deciding where the new API endpoint docs should live, actually writing docs from scratch, and deploying the content.
To start the year, I've been cleaning up my mess, and automating this process away:
- I migrated the API to HonoJS, used Zod for API validation, and a neat middleware for converting that validation into an OpenAPI spec
- I built a pipeline to convert that OpenAPI spec to markdown, and that markdown to HTML (effectively building my own OpenAPI to Docs generator from scratch), so that OnlineOrNot's API documentation gets generated as I write my code
- I wrote about the process
I could have used a third-party to handle generating my HTTP API docs, but one of my strong convictions is that docs are as much a part of your product as the rest of your UI, and I want to be able to easily respond to feedback and change anything as needed.
What's next?
In the coming weeks, I'll be:
- automatically publishing OnlineOrNot's OpenAPI schema to GitHub
- so that it's easier to generate tooling off a specific version of the API without having to worry about it spontaneously updating
- building API endpoints for status pages
- starting with status pages themselves, followed by creating incidents for status pages
In short, I'm trying to make OnlineOrNot fully compatible with being managed via an Infrastructure-as-Code (IaC) solution like Terraform, and I figure Status Pages are good place to start.