Net API Notes for 2022/02/17
New week, new job! More on the job thing under the milestones section. But first, this week's Net API Notes!
Net API Notes is a regular, hand-curated digest of impactful news and analysis for busy API practitioners. Are you reading this and not subscribed yet? Sign up today and be the first to get ad-free, actionable info delivered directly to your inbox.
NOTES
VISUALIZING OPENAPI DESCRIPTIONS FOR FUN AND INSIGHT
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
As part of his ongoing YouTube series, Erik Wilde interviewed Cesare Pautasso on his new book, "Beautiful APIs".
OpenAPI has become the de facto represention of an API's intent in a machine-parsable format. Having a single specification for the bulk of APIs has dramatically expanded the number of non-development folks who can participate in API discovery, design, and usage. However, scanning lines of YAML or JSON can still be daunting for a non-technical audience. Furthermore, emphasis on individual aspects of the text can miss the forest for the trees: the larger "shapes" of consistency and cohesion.
What Cesare's visual representations do is provide a different perspective on API design, one that is both accessible as well as unique. At the very least, the URL hierarchy is put into sharp relief with this rendering, raising questions that may otherwise go unnoticed amidst whitespace or stacked brackets.
It reminds me of a great architect I worked with named Michael Chermside. He created a similar visualization for internal Capital One in 2014/2015. As an API design reviewer, the tool was essential for identifying where concepts were muddy or broke down - something that bubbled up through imprecise or conceptually confused language.
I'd love to see more experiments in this space. Are you doing something similar? Let me know.
7 WAYS TO FAIL AT MICROSERVICES
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
For many companies, microservices have been a boon to team autonomy. However, microservices can introduce more hassle than they are worth if done incorrectly. In a recent InfoQ article, Holly Cummins, an IBM Innovation Leader, shared "7 Ways to Fail At Microservices".
A host of classic software mistakes are mentioned, like resume-driven development and the enterprise hairball. The insight that I appreciated most, however, was how:
"Being distributed does not mean being decoupled."
That is a fantastic point that echoes a recent Twitter thread hitting upon the same insight. Give this article a look.
APIS AS LADDERS
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
In this piece, Sebastian Bensusan writes about the concept of "API Ladders", a model for thinking about API design adopted by Stripe.
The usefulness of the ladder begins with the assertion that the hard part of an API isn't using it, but the time and effort required to learn it. Every rung on the ladder represents an amount of energy that must be expended. In exchange for that effort, a greater set of solutions are within reach.
Everyone begins with the first ladder step; they need help getting started and accomplishing the most prominent tasks. For some, that may be sufficient. Others, however, require additional support for their more nuanced use cases. The introduction of more complex concepts, interrelations, and limitations needs to be logically consistent and incrementally introduced so as not to overwhelm a new user. Finally, toward the top of the ladder, the API must demonstrate design flexibility - allowing it to serve use cases the original authors did not conceive of.
Sebastian's framing is worth spending some time with. After all, it seems to be working for Stripe.
MILESTONES
Also, I have a new job! This week I started as a Delivery Engagement Lead (or DEL) for the Concentrix Catalysts API consultants. I'm joining the fine folks formerly known as PKGlobal; people passionate about high-touch, API-led, digital transformation. The job is building strong, ongoing relationships with care and appreciation for nuance.
I've maintained that theories are only as good as the rigor with which they're tested. I'm excited to continue to evolve API governance and sociotechnical design with the other experts here. Wheeee!
WRAPPING UP
Looking for an API event? Check out NetAPI.events: a collection of upcoming events, presentations, and conferences. Don't see an event? Let me know what's missing, and I'd be glad to add it.
Finally, my thanks go out to this newsletter's Patrons. This week, in the Patron-exclusive podcast, I expand more on my new role, being approached by a sponsor, and (ultimately) why I turned it down.
Till next time,
Matthew @libel_vox and matthewreinbold.com
While I work at Concentrix Catalyst, a mind-expanding hive of experience and practice, the opinions presented above are mine.