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 19

This is my sixth weeknote in a row that I’ve published without publishing a regular post. I’m OK with it. I’m writing a lot, personally and for work, so I’m keeping the habits, just not on here. I’m fortunate to be working with companies right now that put a high value on writing and ask me to spend a big part of my time doing it for them. Consuming too much I read a tweet recently that got me thinking about the amount of content I consume in a week.

Read more →

Weeknote 18

This was a quieter week compared to the last few. I did a lot of personal writing and writing for work. The driving range where I hit golf balls has been closed, so that’s been a bummer. On communication I struggle in my work life finding ways to express myself. I’ve experienced that a lot these past few weeks. My issue is that I use weak language to share my ideas and opinions.

Read more →

Weeknote 17

I had my 20-year class reunion this past weekend. They couldn’t find enough interest in having a larger party, so we had a small gathering at a restaurant with outdoor seating. It was fun, and I was able to remember everyone’s name. I’m now in the habit of using Field Notes as a way to keep notes as I’ve mentioned here before. I finished up one this week and started up a new one that’s part of their National Parks Series.

Read more →

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 →