Stephen Mizell
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.
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 16

This was my first week back to work after my time off, and wow it was tough to get back into the groove. We started homeschooling for the 2021-2022 school year this week. I’m helping out by teaching writing for both kids—my wife heroically handles the other subjects. For writing, we’re working on making up stories together by drawing pictures and then writing out what’s going on. We try to think about how it fits on a story arc.

Read more →

Weeknote 15

Yesterday July 30th was our 10-year anniversary. We celebrated by traveling to the Ocoee River in Tennessee to go white water rafting. We went rafting on the Ocoee on our honeymoon and thought it would be fun to retrace our steps a decade later. The river never disappoints. It’s dam-controlled and always has flowing water and good rapids. There are two different sections you can raft on the Ocoee—the upper and the middle.

Read more →

Weeknote 14

This was another vacation week—one more to go next week. We spent a few days at the pool, I played golf with my brother, and we cleaned out my car for our upcoming trip to whitewater rafting. To give an idea of how long it’s been since I’ve cleaned out my car, I found three toothbrushes from my trips to the dentist under the seats. My dentist gives out goody bags after a cleaning visit that include a toothbrush, a tiny tube of toothpaste, and floss.

Read more →

A Rule of Three for APIs

Leonard Richardson gave a talk back in 2016 called The Magic Arrow. He shared his experiences building a mobile application for the New York Public Library that allowed the patrons to borrow and read ebooks. He found there were characteristics of architectural designs that made them more extensible and reusable, and he summed them up under the idea of the magic arrow. When we draw architectural diagrams, we draw boxes and connect them with arrows.

Read more →

Weeknote 13

I started my long vacation this Wednesday. I’m off until August 2nd and could not be happier. It’s a strange feeling taking time off when you’re self-employed. There are no vacation days. The income goes to zero. You see how much time-off costs you. But it’s worth it. I haven’t done much with my time other than clean and play a 6am round of golf. I’ve tried to stay away from the computer as much as I could.

Read more →

Weeknote 12

Getting into Elixir again A few years ago I started a project using Elixir. I loved working with it. But my motivation for the project fell and I moved onto other things. Fast forward to this year. I started the project back up from with a different perspective. This time, I started focusing on analyzing OpenAPI schemas by looking at all the possible variations—what I talked about as schema entropy. I spent a morning writing a prototype in Python and got some interesting results.

Read more →

Robustness, Tolerance, and JSON Schema

I’ve been exploring the topic of schema entropy, the idea that we can understand the complexity of a schema by exploring all possible variations of the schema. The more variations, the higher the schema. The higher the schema, the more complex it is. When evolving an API, it’s helpful to look at how the entropy of schemas change. For example, with request bodies, it’s necessary to increase entropy for each schema change.

Read more →

Weeknote 11

We took a mini vacation with another family this week. Our friends rented a cabin on a lake with a pool. We spent all our time swimming, canoeing, and lounging around. I love vacations like that. You get a chance to unplug mentally from it all and do nothing or whatever you want. After our trip, we took the kids to see Garden of the Gods for their first time. It’s a beautiful place.

Read more →

Weeknote 10

I’m into a habit of writing these every Saturday when my wife leaves to go to work building bikes. It’s just me and my kids here at home, and they spend the 30 minutes or so I’m upstairs yelling at me that I’m taking too long. I’m OK with it. One day I’ll miss them screaming their frustrations and disappointments at me from the bottom of the stairs. I’ve started spending a lot of time this week stretching to help my lower back.

Read more →

Turning an API Into a Programming Language

What if we could combine the power of HTTP with the universal qualities of URLS to create a way to build an API that works like code? It would be a way to turn the web into a programming language of sorts, to treat an API as if it were code. To explain this weird idea, we’ll think about it in terms of calling functions with HTTP calls similar to how you’d call functions in code.

Read more →