Stephen Mizell
API by Design cover
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.

Buy now


Weeknote 01

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.

Read more →

Weeknote 28

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.

Read more →

Weeknote 27

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.

Read more →

Weeknote 26

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.

Read more →

Weeknote 25

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.

Read more →

How Netflix Reduces the Surface Area of Coupling

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.

Read more →

What If

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?

Read more →

Weeknote 24

I’m coming down this week after a book release last Thursday. I didn’t realize how much different a book would be than a blog post. I know they’re different—obviously—but finalizing a PDF that people would download had a new level of finality to it. Lots of times with blog posts I fix things after I publish them. That’s not possible with a PDF. Once you put it out there, it’s out there.

Read more →

Decay and Entropy

All the way back in 2002, Martin Fowler talked about what he called Design Decay. He says: If you have a notion of planned design, that the design is something that’s right at the beginning, then it’s kind of inevitable that the design will decay. I like this concept of design decay. While I don’t think a design ever perfectly captures the essence of its subject, I think the design does lose its relevancy and accuracy over time.

Read more →

Weeknote 23

It’s already October? This last part of the year always flies by for me. It’s so busy with holidays and birthday. I do love Fall weather, though, which we’re getting a glimpse of now. I didn’t write a weeknote for last week. I was too busy! First, I released my book API by Design. I’ve been researching the topic for several months and writing the content for a couple of them.

Read more →