Hi, I'm Stephen Mizell, a technologist and writer specializing in APIs. You can read about me, check out some of my projects, read things I write, keep up with weeknotes, or get in touch.
New book API by Design
My book API by Design is now out! It's a book about finding ways to measure complexity so we can design and build better APIs.
I don’t think these count as weeknotes anymore. There’s been a lot going on. The biggest change for me is that I’ve taken a full time job that I start March 28th (tomorrow). I wasn’t planning on stopping my solo work, but a few opportunities popped up that I decided to consider. It wasn’t an easy choice to stop working for myself, and it was tough to pick between a few great opportunities, but I’m excited about what’s to come.
I’ve started taking a pottery class. It’s a much-welcomed escape from my digital working life that I don’t normally take. I read and write, but I don’t do much with my hands like this. I recently discovered Pandoc as a great tool for building nice-looking PDFs from Markdown. Murderville was ridiculous. I’m reading How to Be Perfect: The Correct Answer to Every Moral Question by Michael Schur. I’m also trying to finish Dune.
Hyrum’s Law says: With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody. But by itself it’s not all that helpful to me. It’s like saying, “with a sufficient number of people, a room will be overcrowded.” Is that according to Fire Marshalls? Introverts? How big is the room?
This is my first week back to writing weeknotes after taking a long time off. We’ve been locking ourselves down with the recent surges. Our area has been breaking daily numbers regularly and filling up our hospital with enough people to put it into crisis mode. But not everyone feels the crisis as our local schools removed the requirement for students to quarantine after exposure. I took off a few weeks at the end of the year that started with a nasty tornado that ripped through our area.
I’m writing this from a coffee shop. It’s the first time I’ve sat inside one since the pandemic started. I spent several mornings at a coffee shop writing Morning Pages before the pandemic. When you go regularly like that, you get to know the regulars and be known as a regular. They stop asking your name when you place your order. You get to know the staff and the regulars like it’s a little community.
It’s fall now. We have about 10-15 huge trees that are pouring out a steady stream of leaves into our yard. The leaves are beautiful to look at while they’re changing colors and still in the trees. But when they come down, they turn into a sloppy mess. I’ve been coding a lot lately, for experimenting, for building tools for work, and for my own tinkering. Friday, I wrote a Python library for fun called zzip that’s useful for traversing over data and making immutable changes.
I’m writing this again using GitHub Codespaces. I got Hugo working to be able to serve up the local server by setting up port forwarding for port 1313. Port forwarding is a feature in Codespaces, so it’s just a few clicks. Then I provided Hugo with the URL Codespaces created and told it to not append the port. It works, but LiveReload doesn’t because of some protocol issues. I’ll dig more into that later.
Our youngest kid had a birthday. It was a week full of unicorns, pizza, and cake. I created a landing page for my book. However, I think I’m going to move it away from the dedicated domain to this one. I’ve been reading This is Marketing by Seth Godin. I enjoy the way he writes. I’ve been tinkering with an idea. I’m thinking of adding a notes section on this site for shorter writing.
I wrote about coupling in API by Design and the characteristics associated with it. One of those characteristics is the coupling’s surface area which defines the number of resources, schemas, and properties upon which an API client depends. The larger the surface area, the more likely an API change will require an API client change. API consumers can limit this risk by relying on less of the API. Netflix talks about how they use Protobuf FieldMask to allow consumers to specify which fields they use in order to solve complexity issues.
What if someone asked you to design a new API description format like OpenAPI? What would you include? What would you take away? What would you do differently? What would your focus be? As I’ve been thinking about complexity in API design, I had the thought that it might be an interesting exercise to come up with an API description format that aggressively limits complexity in API designs. How would I do this?