REST API Notes for 2018-01-31
Last week, I took a stab at guessing what 2018 might have in store. I cited what appears to be a growing counter-narrative against microservices. I also mentioned we'd take this week to use Steward Brand's Pace Layer Thinking as a scalpel for separating tech fashion from tech foundation.
That exercise, however, turned out to be more work than I had initially expected. It was complicated, in part, by Gartner having published its own derivative model of the same name in 2012. Furthering my annoyance, they fail to mention either Brand or Frank Duffy's earlier theory, "Shearing layers". There's some connections here that are meaningful but I'm still figuring out how to make it coherent.
Suffice to say, the world doesn't wait while I'm clicking down rabbit holes. While I continue to refine the story, let's take a quick peek at what else is happening in the world of web APIs.
REVERSE ENGINEERING ONE'S WAY TO AN OPENAPI DESCRIPTION
ProgrammableWeb has coverage of a new API tool, Swagger Inspector, by SmartBear. SmartBear isn't new for most API folks. And, as described, this new functionality sounds fantastic; simply put, you curl (or postman) a few endpoints, it monitors the responses, and compiles the results in an OpenAPI-compliant document. The execution, however, leaves much to be desired, is more complicated than it needs to be.
As author and ProgrammableWeb Editor-in-Chief, David Berlin, points out, the brand confusion between Swagger and OpenAPI still exists for many developers. Then SmartBear gives multiple tools the 'Swagger' name (Swagger Inspector, SwaggerHub, Swagger Editor, Swagger-UI), each with different usage (online, download) and payment models (SaaS, open source). The final head scratcher is unnecessary dependency between the tools; as David says:
"- when the tool generates an API specification, it actually does so from within another one of SmartBear’s tools; SwaggerHub. So, in essence, the generation of the API definition — an advertised feature of Swagger Inspector — relies on another tool to finish the job. Technologically speaking, the product didn’t have to be designed this way. In fact, Swagger Inspector could probably have done it using an API call to SwaggerHub without ever leaving the Swagger Inspector interface"
Being able to create an OpenAPI document for any web API is great. It is another example of how tools are furthering the web API space. But, as a product, Swagger Inspector is a step forward when it could have been a leap. Overcome the brand wrangling and forced-tool interdependence, and there's something there.
A DETAILED COMPARISON OF HYPERMEDIA TO CRUD
Mike Hibay has created a detailed and thoughtful comparison of hypermedia to CRUD. APIs, where developers mimic CRUD operations with the POST, GET, PUT, and DELETE verbs, respectively, remain popular. It's simple for folks to grok. However, as he illustrates, continuing this model for all but the simplest APIs results in suboptimal results.
Later on Mike states, "I believe it is time we stop writing snowflake services on the internet". Oh boy, if only.
JSON-HYPER SCHEMA CLOSE TO BECOMING SPEC
JSON Hyper-Schema has been, increasingly, on my radar. Aaron Hedges has a great post for getting started. JSON Hyper-Schema adds support, in the form of 'vocabularies', for links to normal JSON Schema. This allows for validation of a payload either out-of, or into an API.
There's nothing that says an API must return JSON. In fact, one of the beautiful things about web APIs is that they are agnostic to the particular form of the data returned. However, if you're heavily invested in JSON, and are looking for ways to programmatically check for payload correctness, give JSON-Hyper Schema a look.
MILESTONES
- Keith Casey has published, in conjunction with Lynda.com, an OAuth and OpenId Design Course. If you can't articulate the differences between authentication and authorization, this is a great place to start. If you're not a current Lynda.com member, they do have a free trial options to get started. Another option is the fine write up of OAuth and OpenId on the Okta site. While it is a specific vendor solution, their dev pages do a good job explaining the fundamentals.
- Announcing news the Friday before the holidays is one way for it to go (mostly) unnoticed. For those that might have missed it, one-time API darling, Keen.io, has been acquired by Scaleworks. Is is a humble exit for the once award winning startup.
- In more (joy)ful news, Joyce Stack, frequent API community contributor, has been promoted to the role of "API Architect" at Elsevier. Congratulations to Joyce and best of luck in her new role!
Til next time,
Matthew