REST API Notes for 2018-03-13

In March, numerous API luminaries have, seemingly, sprung to life. Publishing weekly is infrequent enough to aggregate similar thought while being frequent enough to track emerging thought leadership. Different authors, when they agree, reinforce valuable messages. If they disagree, the contrasting points help the truth stand out in sharp relief. This week's collections are all about API Documentation and microservices.


Not all API Documentation is the same. Last week Keith Casey shared a gangbusters piece articulating not one, not two, but three different types of API documentation. As I mention in my recently published guidance for API product managers, different audiences will need different things from an API. This, also, extends to the API documentation.

Phil Sturgeon spent some time documenting the maturation of his Design-First workflow. It is a fantastic blueprint teams can follow. Kin Lane was impressed.

Much of that API Design-First workflow wouldn't be possible without the OpenAPI specification. For an example of how eBay uses API descriptions in their business, Shekhar Banerjee has shared an overview.

Finishing up the documentation section, Faria Rehman has written about the most common mistakes that developers make in their OpenAPI 3 files. Faria works as a support engineer for APIMatic. As such, this is valuable aggregated analysis from a tool vendor that has supported the format since it was a release candidate.


I regularly feature the work from CA's API Academy, and for good reason. The community is lucky to have a group dedicated to not only advancing the API craft, but regularly sharing as much of their work as they do. They have been on the road this spring, and that means their thoughtful work has been popping up online.


Irakli Nadareishvili announced the IANA has accepted his registration for a new Mime type, 'Hyper'. As Michael Hibay rejoiced, "[hyper] opens up the options for any user agent to negotiate any format they choose". I'd love to hear what people's experiences are like giving the new mime type a go.

Phil Sturgeon announced that Speccy, his project, is now not only an OpenAPI linter, but also checks for quality rules. If you are building an OpenAPI workflow for API management, this is certainly a tool worth considering.

Finally, Hootsuite announced the availability of a tool for microservice observability. More than a "microservice deathstar", it gives those managing these deployments a reasonable shot at awareness with microservice's heightened levels of complexity.


I recently updated with the latest crop of events. If you have an event that isn't listed either respond to this note directly or send me an email at ''. Not a problem to help people connect.

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.