When we design an API—among many things—we’re designing how we think the API will change. We often reach for versioning to handle this, but versioning is a small part of the change discussion. For instance, will the versions be for the entire API or for individual resources? Will we support each version forever, or will we deprecate and sunset all or parts of versions? And at what point do we switch to a new version?
One of my favorite practices I’ve adopted in my professional career is to write about everything I’m working on or thinking about in a place coworkers could see. I thought I’d share the ways I’ve made this work for me. Make your own space The goal of having your own space is so you don’t have to think about or care about making a new page. Without it, you feel like you have to find the official place to write something authoritative about an official topic.
I started out writing these weeknotes on HEY World. I liked how easy it was to write there—just send an email to email@example.com, and it would create a post for you at https://world.hey.com. It also supported an email subscription feature. However, I set this goal a few weeks ago to start writing more, both for fun and professionally, and just this week I started from scratch on this site with Hugo.
Fine, I’ll start a blog. Or I should say restart a blog. I started writing on this site several years ago. I was wanting to write more professional content around my work. I picked Middleman as a build tool for the blog and off I went. I wrote a few posts on it. Five or six over the course of a couple of years maybe? After some time, I converted the site over to Jekyll because GitHub would build, deploy, and host your site for free.
I’m working on a personal project with the goal of giving insights into the complexity of an API design. We don’t have many ways or tools for looking at complexity, and the ones we do require experience and knowledge of API design. I’m hoping to find ways to look at complexity through a different lens. One way I’m working on now is what I call schema entropy. An intro to the idea of schema entropy Schema entropy is a way to look at the complexity of an API schema by determining how many variations of the schema are possible.