Net API Notes for 2021/06/30 - Issue 167
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 the U.S., folks are about to stream to the exits for a long holiday weekend. However, before they do, let's squeeze in one more Net API Notes. This time I've collected three pieces about the best way to lead API change within an organization.
NOTES
THREE REASONS TO DO API DESIGN REVIEWS
STRATEGY / DESIGN / DOCUMENTATION / DEVELOPMENT & TEST / DEPLOYMENT / SECURITY / MONITORING & OBSERVABILITY / DISCOVERY / CHANGE MANAGEMENT
Arnaud Lauret, the API Handyman, has been on a writing tear lately. His latest is entitled "3 Good Reasons to do API Design Reviews". He starts with a fact that anyone that has contributed to an API style guide quickly realizes:
"If an API is 100% consistent with itself, with outside world common practices, with design guidelines and existing APIs, it unfortunately still can be a terrible API."
Design review should never be human linting of an OpenAPI description; machines are great for performing tedious tasks. Instead, the design review should be an opportunity to review the Job-to-be-Done, assess the proposed complexity, and ensure long-term business value. Think of it as paired programming, but for an interface design.
DEVELOPING AN ENTERPRISE-LEVEL API STRATEGY
STRATEGY / DESIGN / DOCUMENTATION / DEVELOPMENT & TEST / DEPLOYMENT / SECURITY / MONITORING & OBSERVABILITY / DISCOVERY / CHANGE MANAGEMENT
Sophie Rutard, of Euler Hermes, recently appeared on the Stoplight.io podcast. She was there to discuss how enterprise programs promote quality API production.
In the write-up, Sophie listed six places to focus required to realize total API value:
PROPER API MANAGEMENT
There are some things, like identity, that should be centralized, full stop. API Management has been doing this for some time. There should also be some centralized function, like API governance, responsible for culling feedback and recommending guidance at the level that they are uniquely positioned to see.
EXECUTIVE SUPPORT
The right executive backing is critical in unblocking cultural silos that can impede holistic approaches to consistency and cohesion.
API DESIGN GUIDE
The design guide is less about having a tome of "thou shall" and "thou shall not". Instead, when done correctly as a living document, it becomes a conversation attractor, surfacing assumptions and creating insights.
MAINTAINING A HUMAN TOUCH
Like Arnaud, above, Sophie recognizes that not everything can be automated. Making an API design intuitive to use, for example, is not something that can be detected with a linter.
BUSINESS CAPABILITY CENTRISM
How do customers think about your capabilities? Do your APIs map to their assumptions, or are boundaries driven by producing developer convenience? I gave a talk about this before (Internal Organization != External Perception) and strongly agree with Sophie's characterization.
DEVELOPER RELATIONS
And, finally, there is establishing virtuous feedback loops. It is essential to be engaged with the end-users of any product. For APIs, that means developer relations to excite, educate, and expand the value possible.
There's much more in the podcast. If any of these topics resonate, give the podcast a listen.
75X GROWTH: SCALING POSTMAN ENTERPRISE ACROSS PAYPAL
STRATEGY / DESIGN / DOCUMENTATION / DEVELOPMENT & TEST / DEPLOYMENT / SECURITY / MONITORING & OBSERVABILITY / DISCOVERY / CHANGE MANAGEMENT
There are all sorts of articles online that describe how to make an API or perform a given action on an API management software. However, stories starting with a good idea, obtaining executive buy-in, and growing it across a company are much rarer. Thankfully, Patrick Millais, writing on the PayPal technology blog, details his experience doing just that.
Creating groundswell for an API-related initiative is no small feat. Patrick's area enjoyed the collaboration, productivity, and discoverability they got from Postman. But to truly take advantage of API best practices and overcome tribal knowledge trapped in domains, they needed to get others on board.
The whole piece is worth a read. One bit that I appreciated, in particular, was how Patrick used the limited number of licenses to his advantage. The viral demand created a waitlist, which was then used for discovery activity, quantifying hot spots, compiling needs, and approaching the appropriate accountable executive to get executive buy-in.
If that sounds like a bit of what Sophie was talking about, you'd be right. At some point, your organizational mobility will be a factor of not just your tech acumen but your ability to influence change. Pieces like this illustrate how that is possible.
MILESTONES
- Productivity API and Automation Platform Nylas raises $120 million
- Data from 700 million LinkedIn users have been made available for sale online. The seller claims the data was obtained by exploiting the LinkedIn API.
- AsyncAPI 2.1.0 has been released.
WRAPPING UP
Over the past week I've had the good fortune to get some writing done. One question that I've gotten, since joining the Postman Open Technology Program, is "What does Open Technology mean?". Postman has published my blog post explaining some of my thinking. I've also got a couple of new pieces on the blog: "How Versus Why Questions" and To Change Behavior, Change the Environment.
I'm also looking for events, be them API, architecture, software management, or anything in-between. Got a live, in-person meetup or conference coming up? Check out NetAPI.events! If something is missing, let me know, and I'd be glad to add it.
Finally, thank you to my Patreons. Your help ensures that this newsletter is free of advertising, information selling, or paywalls. Because of your support, we all win!
Till next time, Matthew
@libel_vox and matthewreinbold.com
While I work at Postman, who's astronaut mascot is so gosh darn squeezable, the opinions presented above are mine.