Net API Notes for 2021/06/10 - Issue 165

Net API Notes is a regular, hand-curated digest of impactful news and analysis for busy API practitioners. Are you reading this on the web and not subscribed yet? Sign up today and be the first to get ad-free, actionable info delivered weekly to your inbox.

In this Net API Notes, I'm zooming in a different way than the API trends seen in the last edition. I've got an intriguing approach to quantifying schema complexity, an excellent primer on when to consider event-driven architectures, and a thought-provoking call to systems-thinking action. Let's begin.



'Yo Dawg' meme with text that reads "I heard you like schemas so I made a schema for your schema so you can validate your schema's schema against the official schema."

Good API design is so much more than exhibiting a consistent vocabulary across interfaces (although that certainly helps). The more complexity inherent in a design, the harder the code that supports ii is to read, understand, debug, and test. All of these things make change slower and more expensive. And the more challenging to change, the more likely bugs will take root and propagate.

Complexity is bad. However, quantifying this complexity in a non-subjective way is hard.

That didn't stop Stephen Mizell attempting, however. In his blog article, "Understanding API Complexity Through Schema Entropy", Stephen attempts to capture one aspect of complexity that, otherwise, goes unnoticed.

What Stephen lays out here is incredibly compelling for API designers. I look forward to seeing where he takes this.


Matt Heusser published a TechTarget piece on how to evaluate event and message-driven architectures for your projects.

In modern software systems, developers are likely to come across both event and message-driven approaches to distributed systems. Matt's guidance goes into depth about both and discusses the pros and cons of each approach.

The bottom line is not that one approach is inherently better than the other. Like all architectural answers, "it depends". However, Matt's piece will help identify the most important criteria for that decision.


I want to end with some thoughts at the system level. Jessica Kerr argues that linear thinking is not enough for distributed systems in her presentation, "Systems Thinking for Developers". (The site contains several valuable summaries and references for further reading. However, if you want just the video with playback controls, check out the recording on Vimeo).

As a framing device, Jessica compares the cold, calculating logic of John von Neumann with the lesser known but no less influential, Gregory Bateson. He helped extend systems theory to the social and behavioral sciences.

"The computer is only an arc of a larger circuit which always includes a man and an environment from which information is received and upon which efferent [outgoing] messages from the computer have effect." - Gregory Bateson

What makes Gregory's work and Jessica's talk relevant for APIs is recognizing how subsystem interact within larger systems. For example, Von Neumann precision is necessary to perform exponential backoff and retry. However, systems thinking is required to understand the subsequent "thundering herd" problem.

Successful API design is more than just delivering a piece of code into production. Success requires an ability to think at multiple levels of scale, simultaneously. The answer as to why we do something always comes from the larger system.

"Writing correct code can be an exercise in logic, but knowing what is correct is an exercise in systems thinking." - Jessica Kerr

Great stuff. If you haven't delved into systems thinking or want a refresher, I'd highly recommend this talk.



Correction! In last week's newsletter on near-term API trends, I referenced Postman's latest state-of-integration report. However, I linked to the wrong location. If you want to get yourself a copy, head over to the State of API landing page.

Finally, thank you to my Patreons. These upstanding folks keep the newsletter free of advertising, information selling, or paywalls. Because of their generosity, the rest of the community can keep getting these notes for free.

Till next time, Matthew

@libel_vox and

While I work at Postman, where normally-sweet gumdrops are bitter in comparison, the opinions presented above are mine.

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.