Net API Notes for 2019/12/05 - Issue 116
Hopefully, for those of you that celebrated Thanksgiving last week, you had a good one. People's customs during that time vary. I try to spend a smidgen of time considering what I am thankful for. This year, it occurred to me how grateful I am for this creative outlet.
There are times when the day-to-day at the factory is more of a grind than an aspirational Willy Wonka playground. When this happens, it is a gift to play with words for a few hours. The reward is a finished newsletter where once there were only fragmented browser tabs and vague allusions to something meaningful.
Thank you for letting me entertain and inform you, even if only occasionally. I'm thankful for it.
Now, onto the notes!
NOTES
ON API STYLE GUIDES
Holger Reinhardt recently shared his thoughts about the value (and challenges) of publishing an API style guide for a company.
"In my conversations engineering knew about our guide, and maybe read the intro, but I could not shake the feeling that no one really read it. Maybe flipped through it, but not read it. And only a few very visible guidelines were applied, but a lot of the deeper knowledge and guidance was - kind of - ignored."
This reminds me of a presentation that Smart Bear's Emmanuel Paraskakis gave at the 2016 Gluecon conference:
Creating guidance that is impactful is no easy feat. There's a delicate balance between comprehensiveness and brevity. I've also been criticized for being too conversational. "Just tell me what I need to do" is a common criticism, which is often followed by "I understand the how but you haven't explained the why".
An important step that my team has been working through with our latest standards iteration is being much more consistent with language for what is required, what is strongly suggested, and what things are only nice-to-have. We're following IETF's RFC 2119 example. This means using a "must", "should", "may" to indicate each of these different types of guidance (and only these words).
Another thing that we're currently doing is disassembling the kitchen sink. After several years, the standards document accrued several things that, in retrospect, should have been separate documents. There are the standards themselves (or a 'style guide', if your company culture is more permissive). Then there is a "cookbook". These are design solutions to everyday situations, like handling binary data, development teams find themselves in. Then there is common practice documentation; these aren't recipes and these aren't standards. Rather, these are the set of things that developers should know to be successful in the larger company ecosystem.
Like microservices, each document is narrowly focused on doing one thing and independently deployable. We also are able to spend less time repeating ourselves during the course of API design collaboration: rather than writing up, for the hundredth time, how a string value should be a tightly bound set of enumerated values, we simply link to the appropriate anchor tag. There the developer finds the canonical description of how to do it and why it benefits both them and the consumer.
If you think an API style guide might be of some benefit to your organization but don't know where to start, check out APIStyleGuide.com.
MESSAGE FORMATS IN DEPTH
In discussing alternative message formats, like gRPC, I spend much time unpacking hype, rumor, and hearsay. For as much as the humble JSON syntax has enabled, it is often cited as the Achilles' heel of distributed architectures.
Tim Bray recently went deep on message formats. As he says in his introduction, "Much of what people believe to be true is not." Are other formats 'more compact' and 'faster over the wire'? Surprise! It depends!
The whole piece is, pound-for-pound, closer to gold than the fool's alternative. For example, I thought I had a good handle on how much a breaking change is a no-no in APIs in general, and pub-sub in particular. However, I had no idea how nasty it gets if one is using a binary format rather than JSON:
"Publish/subscribe is basic to event-driven software, and the whole point of pub/sub is that the event generator needn’t know, and doesn’t have to care, about who's going to be catching and processing those events. This buys valuable decoupling between services; the bigger your apps get and the higher the traffic volume, the more valuable the decoupling becomes. But it also means that you really really can’t make any backward-incompatible changes in your event formats because you will for damn sure break downstream software you probably never knew existed. I speak from bitter experience here."
"Now, if your messages are in JSON, you can probably get away with throwing in new fields. But almost certainly not if you're using a binary encoding."
Fantastic read. Just stop here and read that. Seriously. I won't even be offended. Much.
MILESTONES
- Ketting, a generic Hypermedia/HATEOAS client for Javascript, just hit version 5.0. The new version includes support for Siren, a more lightweight OAuth 2 library, and more.
- Bearer has announced a closed beta of its API monitoring extension
- As announced by Phil Sturgeon, OpenAPI's latest tweak clears the way for JSON Schema
WRAPPING UP
This past couple of weeks have seen a tremendous number of additions to NetAPI.events. If you're interested in upcoming, in-person API events in 2020, check it out. And If you know of a meetup, hackathon, or conference that should be added, let me know.
Finally, thank you to the generous Patreons who have said that this newsletter has financial value to them. I appreciate any and all caffeine subsidies thrown my way.
Till next time,
Matthew @libel_vox and matthewreinbold.com