REST API Notes for 2017/07/05

Last week I was in Chicago teaching API design. The weather couldn't have been more perfect; even the night-time lightning show that rolled off the plains and onto my hotel window was reminiscent of childhood summers. Before packing up and flying back to the increasing boil of DC, however, I was able to gather up the latest API notes for this newsletter.

API VERSIONING

Versioning an API, and how you version, still remains one of those decisive issues in API design. The universal need to support change (just a moment, hypermedia folks), combined with no obvious "right" answer, makes for some heated debates. Having designed and built APIs that have tried, at different times, the strategies that Troy Hunt so eloquently described, I'm firmly in the "it depends" camp.

That's why I was pleased to read Google's Dan Ciruli's straight-forward post, "Versioning APIs at Google". While we may be on different sides of the fence in our respective orgs (Google is a "major version in the path" place, my employer uses headers on canonical resources) I love the deeper message:

"Versioning APIs should be done according to a consistent and comprehensive policy."

That goes not just for versioning. It is one thing to consume APIs across company lines; there's an assumed diversity of opinion, experience, and culture that integrating developers need to account for in the API designs. But, within the company boundary, there should be a consistency of approach.

API DEVELOPER EXPERIENCE

This next piece is a twofer. In her piece "10 Things I Hate About Your API", IBM Developer Advocate Lorna Mitchell articulates the poignant bits of Amanda Folson's PHP[tek] talk. Lorna, specifically, focuses on the role of developer experience in running a successful API program.

MICROSERVICE DESIGN CANVAS

Decomposing an application into microservices can be difficult. Before I go, I wanted to mention that Matt McLarty recently shared his microservice design canvas. It is based on the lean canvas approach and helps developers to identify and capture the most important, up-front attributes of a service before building it. Matt walks through two examples, comparing and contrasting how the differing nature of the services are reflected in the canvas.

Have you used the microservice canvas with your own work? If so, what was your experience like?

WRAPPING UP

I've updated webapi.events with the latest, greatest API events happening around the world. If you have an upcoming event that isn't listed, let me know! I'd be glad to talk.

Until next time, Matthew (@libel_vox and https://matthewreinbold.com)