Net API Notes for 2021/01/27 - Issue 151

It's that busy, performance-management review time of year. Let's jump straight into the notes.



Hey, remember hypermedia? The technique sprinkled throughout every API presentation circa 2015? The term that is now only occasionally referenced?

Daniel Little, in his piece "Practical Hypermedia Controls", starts with a theory. He posits that we don't see hypermedia more often in the wild because:

  • People don't have that many real examples to emulate
  • It does require a bit more effort upfront

People setting out to create a hypermedia API can quickly get overwhelmed; which format is "correct"? Which media type? What the hell is a curie? How will I get that contract app-developer to care? Daniel doesn't have all the answers. However, his guide provides a very approachable way of getting started.


Erik Wilde recently celebrated one year of video interviews on his YouTube channel. One of his most recent guests was nomadic tree raconteur and compulsive covid test-taker, Phil Sturgeon. Together, they discussed the importance of API linting with Spectral.

Spectral is an open-source JSON/YAML linter. What makes it great is that you can create custom style guides based on the rulesets and guidelines folks in your company need to follow. Then Spectral can apply those style guides against structured data, like an OpenAPI document.

Erik and Phil's conversation pairs well with a recap of Jay Dreyer's talk, "How to Manage 1000+ Specs At Scale". The author incorrectly uses the term "API Spec" when they mean "API description written to the OpenAPI specification". Setting that nitpick aside, however, the lessons on display are still worth a person's time. In any scaled API program, linting is a must for a consistent and cohesive API design approach.


Uwe Friedrichsen has written a compelling series on the fallacies of microservices. Now, in his seventh and final part, he does an about-face to describe when microservices make sense.

For years, I've adopted the microservice premise from the former API Academy folks: all benefits of the architectural style could be boiled down into reducing communication overhead. Uwe adds a bit of color back to that black and white definition. He maintains microservices make sense when you:

  • need to move fast
  • face disparate non-functional requirements

There's much more in the piece.



I (finally) got the transcript of my talk, "Why AI Success is API Built" posted online. I hope it will be a useful introduction to AI (and the various issues that accompany it) for folks.

Switching gears, those that have worked with APIs for any amount of time intuit the power of abstractions: APIs suppress portions of modern software complexity behind an understandable interface. Thus, one's mental bandwidth is freed to focus on solving the task at hand more fully.

Before the last four years, I did not understand the privilege of taking an "apolitical" stance. Ignoring the legislative stuff and assuming everything would always be OK, relative to me, was a luxury I didn't acknowledge. With that free energy, what did I do? Passionately defend trivial things, like which shade of blue is best.

In his 1996 "Declaration of Independence of Cyberspace", John Perry Barlow proclaimed the internet (and those who work on it) beyond such legacy code as governments. While it remains a formative document for me, the past four years have demonstrated what a leaky abstraction that mindset is. It turns out there's a pretty tight coupling between our nation's health and the health of our democracy. Cyberspace is just another aspect of shared space. As such, it is just as delicate and prone to breakdown without proper care and maintenance.

We'll never be a "perfect union". However, striving to that ideal is not about the reward at the end, but the better people we become alone the way. In the last few years, the abstraction I maintained became too problematic to ignore. For the first time, I marched for something. I wrote letters. I even donated to political campaigns, something which a decade ago I thought was for suckers. I'm different because of the effort.

Competence matters. Caring matters. Overcoming cynicism and crassness matters.

I, too, had a weight lifted after the inauguration last week. It felt like a portion of my daily operating cycles had been freed up. But that naivete about how the system works? Pretending that foundation doesn't exist while simultaneously building a life on top of it? I've abandoned that abstraction. It is time to design a different one.

There's so much to fix in front of us. But last week was an important step in the right direction.

Thank you to the Patreons that have been there throughout this journey. I appreciate the support throughout these past several years. With any luck, we'll have several years more!

Till next time,

Matthew @libel_vox and

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.