REST API Notes for 5/24/2017 - API Clichés and Mulesoft Joins OpenAPI Initiative
HEARD IT ALL BEFORE
Despite my better judgement, I'm a habitual Twitter user. I'm 90% certain that at least some of my graying hair can be attributed to it. But occasionally there are times, like last week, where I'm reminded of the wonderful conversation that happens there.
3Scale's Nicolas Grenie, while attending the #APIMixtape Conference, started it by tweeting "there should be an #api conference bingo: SOAP Sucks, blame @linkedin and @twitter for shutting APIs, and that GraphQL is the future". Funny because it's true. Attend any API-themed conference and themes begin to appear. The community saw Nicolas's list and quickly added the following presentation clichés:
- Stripe has awesome API Documentation (Nicolas Grenie)
- Someone says Swagger when they meant OpenAPI (Nicolas Grenie)
- Hypermedia would dominate if only we had better tools (Lorinda Brandon)
- Microservice all the things (Lorinda Brandon)
- APIs just Need Better Monitoring (Allen Clayton)
- IoT is the Future of APIs (Allen Clayton)
Someone also mentioned the API conference picture de rigueur: a semi-submerged iceberg. It, with the majority of its mass below water, is meant to illustrate that unseen size of "private" APIs compared to what the public can see. For some bizarre reason, the iceberg also always seems to be the same one (apologies to Netflix's Daniel Jacobson).
The iceberg isn't the only hackneyed visual. There's the exponential growth curve from Programmable Web; just change the year on the horizontal axis. More recently, some form of Twitter's microservice complexity pops up. And the power of standardized interfaces is almost always illustrated with Lego. So (1) much (2) Lego (3).
People struggle to understand abstractions, which is why successful clarifying metaphors get reused. Case in point: the excellent Nordic APIs piece by Art Anthony that, yet again, makes the Lego comparison. People should tread carefully, however. Just because there is a common story we tell ourselves doesn't mean there isn't a better one out there. I challenge those that write and present about APIs to find it.
Have your own API conference cliché you'd like to share? Let me know.
ONE API DESCRIPTION TO RULE THEM ALL?
API description specifications are useful for capturing an API's intent in a standardized format. The human-friendly renderings can be used for service discovery, while the machine-readable versions power tool-chain automation. While the advantages of using an API Description may have been obvious, however, which specification to use - API Blueprint, OpenAPI Specification (or OAS, formerly known as Swagger), Mulesoft's RAML, etc. - was less clear. Tools like API Transformer helped if translation was needed after an API description had been created, but not if starting from scratch.
That changed last week. As announced by Tony Tam, Swagger's initial author, Mulesoft has joined the OpenAPI initiative. They follow Apiary, shepherds of API Blueprint, who joined in 2016. Tony should be lauded for his incredible work to reach this milestone.
However, I don't agree with Tony's sentiment that the "format wars" are necessarily over (or that it was a "war" to begin with, but that is another digression). Less than a week prior to Tony taking his victory lap, Hitch launched the AsyncAPI specification. It attempts to do for asynchronous APIs what OAS did for RESTful ones. While the authors freely admit they were inspired by OAS, there's enough difference here to warrant a closer look.
I just wish we'd reconsider our embrace of YAML to write these things. I'm with Kevin Swiber on this one - we can do better.
WRAPPING UP
A handful of folks reached out with events for webapi.events. Those are now live, along with plenty of additional info I've pulled together. If you're looking for somewhere to play API conference bingo, check it out!
Until next time, Matthew (@libel_vox http://voxpop.co)