Net API Notes for 2021/02/24 - Issue 154 - OpenAPI 3.1
Big things afoot this week! To the notes!
NOTES
OPENAPI 3.1 RELEASED!
The OpenAPI specification has a new version! This version, notably, provides full compatibility with JSON Schema 2020-12. If you'd like to learn more about JSON Schema, the proposed IETF standard, their website is now updated with the latest greatest on Draft 2020-12.
JSON, as many of you know, is syntax. It is the common structure by which today's net APIs communicate. As the name implies, JSON Schema allows practitioners to add a layer of meaning to the words that appear within the brackets and colons. Lots of things can benefit from standardized language exchanged across a company. I'm excited to see how companies use this format to align terms and concepts across their interface portfolios.
But wait! There's more! Lorna Jane is a serious proponents of webhooks. Happily, they get a serious boost in the latest release. She goes into more on her blog. I appreciate Lorna taking the time to describe the difference between webhooks and callbacks, and why that matters.
Need more information? There's a great write-up on all the considerations and concerns on the OpenAPI blog. Prefer your explanations in video form? Contributors Darrell Miller and Ron Ratovsky have you covered.
THE FUTURE OF API SPECIFICATIONS
If you haven't had enough of API specifications, Fran Méndez has some thoughts. If you're a longtime reader of these notes, you're familiar with Fran's work on the AsyncAPI specification. He's released a video, "The Future of API Specifications".
Fran shares a bit of the behind-the-scenes of what it's like launching a new specification. He also provides an overview of the entire API specification landscape. Chances are, there are plenty more formats available to you than you might have expected.
Will there be 'one spec to rule them all' in the future? Fran's answer may surprise you.
API DESIGN MAXIMS
So maybe you're on board with capturing your API's business intent with an API description. What makes a good design?
For that, I return to one of my favorite API touchstones, Joshua Bloch. In this collection, from October 2006, Joshua outlines 39 maxims on what makes an API design good.
This is a high-level piece. When Joshua worked on this, he was thinking of code-level APIs in the Java language. However, it turns out that good interface design principles remain sound despite occurring over different protocols.
Unfortunately, there's no one way to have the "right" design. As Joshua describes:
"API design is an art, not a science. Strive for beauty, and trust your gut. Do not adhere slavishly to the above heuristics, but violate them only infrequently and with good reason."
If you'd like to see these maxims in spoken form, there's a classic Google TechTalk available.
What's more, if you'd like to see Joshua revisit API history a decade later, check out this QCon talk filmed in 2018. So much of the same problems we wrestle with today are the problems we wrestled with then. From the presentation, Joshua shares a quote that I could have wrote yesterday. However, it is from 1952:
"-there still remains the considerable task of writing a description so that people not acquainted with the interior coding can nevertheless use it easily. This last task may be the most difficult." - David J. Wheeler, The Use of Sub-routines in Programmes
MILESTONES
- RapidAPI acquires Estonian startup Paw, creators of a Mac app for designing and testing APIs.
- Patch, a company that has created an API for carbon offsets, has raised $4.5 million in financing.
- APIDeck is now a JSON Schema sponsor. That is notable since JSON Schema has no employees and relies on volunteer effort. Financial donations are welcome.
- Wren, a site that allows for carbon offsetting, has a new API.
- Curity.io accumulated so many resources, tutorials, and videos that they had to go and upgrade their search engine. Check it out!
- Facebook announced the tenth version of both their Graph and Marketing APIs.
WRAPPING UP
A year ago, I did a round of Q&A. It remains one of my favorite editions in recent memory, and I'd love to do it again. If you question the API industry, API design principles, or API governance, let me know. I'll be gathering together and answering some of the most word-provoking for a future newsletter.
I'm also seeing a handful of API events popping up. Still virtual, of course, but they are an opportunity to learn, regardless of where in the world you are. You can find the list at NetAPI.events.
Finally, thank you for your attention and to the Patreons who enable this newsletter to remain ad-free! That means a lot to me. And, based on the subscription numbers, others too!
Till next time,
Matthew @libel_vox and matthewreinbold.com