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.
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?
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.
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.
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.