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.

A crazy man in front of disparate information, crazily attempting to piece things together

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.


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.


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 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.


Til next time,


@libel_vox and

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.