Net API Notes for 2021/11/12 - Issue 181
In this issue, we return to the importance of API-Design First, get into the weeds on API-First product development, and - now that we've shipped the product - delve into the dreaded "dangerous delay". Onto the notes!
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.
NOTES
WHY API DESIGN FIRST
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
If you've been watching the API space for as long as I have, you risk displaying "tenured professor syndrome": you assume that the basics are obvious, and everyone knows them. Meanwhile, beginners without years of experience wonder why the hell you're whinging on about some obscure nuance that intellectually lies miles over the horizon from where they are.
According to the 2021 State of APIs report, 76% of respondents reported less than five years of API development experience. The industry may be more than two decades past Roy Fielding's dissertation, but the people executing those interfaces are still relatively new.
That's why I appreciated Lorie Pisicchio's piece entitled, "Why Design First When Building APIs. She does a beautiful job defining first principles, framing the considerations, and presenting a compelling argument. If you are working with folks who need a primer on the importance of pursuing interface design before programming, give this article (and accompanying video) a look.
ALL THE TACTICAL DETAILS OF API-FIRST PRODUCT DEVELOPMENT
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
Jayadeba Jena is in the midst of a comprehensive API-First series over on Medium. In "A Playbook for API-First Transformation", Jayadeba presents a level of process detail that often goes missing with these publicly available stories.
I would caution against applying everything here verbatim. For example, I can't entirely agree that the purpose of a design review is only to assess "the objective stuff". That said, if readers interpret the piece as less boxes to be ticked in their efforts and more as an example of how detailed some of the roles, responsibilities, and nuance are, it is a win.
While I'm on the topic of design reviews, the API Handyman continues dropping thoughtful insight based on his impressive experience. In "Choosing Between DateOfBirth and BirthDate", Arnaud demonstrates how even these seemingly trivial decisions can aggregate into considerable DX impact.
THE "DANGEROUS DELAY" IN API ADOPTION
STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY
Keith Casey doesn't blog as much as I'd like, but it is always worth paying attention to when he does. His latest, "The 'Dangerous' Delay In API Adoption", illustrates one of the most harrowing points for any API developer.
"We can't tell the difference between "not adopted yet" and "never going to adopt" until well after the fact."
When I say any, I do mean internal as well as external APIs. In previous enterprise roles, seeing a six-to-nine month delay between when a producer makes an API available and when it began to be used was extremely common. Of course, waiting half a year for feedback is not the kind of agile, iterative environment most aspire to. As a governance group, a significant concern was answering whether we were shipping faster than we could learn. Crafting the processes and communication to learn faster than one can ship is a critical differentiator between an API program that merely survives and one that thrives.
MILESTONES
- Meta (formerly Facebook) has struck a deal with Github" through which the two teams will work together to invalidate Facebook API access tokens that have accidentally been uploaded and leaked inside GitHub repositories" . Sounds like a good idea.
WRAPPING UP
Hey, hey! There have been several new pieces up on my blog in the past couple of weeks:
- Why Is There No 'Correct' API Lifecycle?
- Pandemic-Led Digital Transformation; You're Doing it Wrong
- Finding API Governance Balance With Polarity Mapping
I've also had the pleasure of appearing on an episode of Erik Wilde's "Getting APIs to Work" show. In the YouTube video, we discuss the 2021 State of the API Report.
If you haven't already, check out the LinkedIn API and Web Services Professional Group. There is also a list of upcoming API meetups and events on NetAPI.events.
Before I go, a big "THANK YOU" to my Patreons! Their support helps keep this newsletter is free of advertising, information selling, or paywalls for everyone's benefit.
Till next time, Matthew
@libel_vox and matthewreinbold.com
While I work at Postman, where internal discourse might be mistaken for "sprinkles" and "rainbows", the opinions presented above are mine.