A month ago, I was presenting in Fosscomm, a conference about Open Source, Open Standards and Open Innovation.

My talk was about APIs and Linked Data. It was inevitable to mention JSON-LD and Hydra, and since the audience was mostly consisted by developers I could experience the phenomenon that Kin mentions on his post:

The Biggest Obstacle For Hypermedia Adoption Is The Cognitive Load Of The Average API Designer

They could understand that JSON-LD and Linked Data in general are partially a better paradigm for approaching APIs, but versioning was mostly what worried most of the attendees.

My presentation can be found below:

A good API is like a nice rap flow.

Everything falls into place and makes sense.

Versioning: The never ending Curse?

Let’s face it: you will at some point have to introduce breaking changes to your API. Most of us plan for this, and try to mitigate the consequences, by versioning. There are loads of ways people out there are versioning – introducing a new subversion with every minor change, bundling changes into major version releases, using content negotiation to manage different versions of resources, etc – and people bicker to no end about the best way to do this. But if one thing is becoming clear, it’s that the way you version your API doesn’t matter – the way you communicate does.

Good communication with your consumers is the key to easing transition to and adoption of new iterations of your API, and this means:

• Be transparent about how you are going to version (or not version) your API from the beginning.
• Let your consumers know well in advance what changes you’re about to introduce (and maybe even say why!).
• Keep older versions around long enough for transitions and communicate a lot about deprecation – and even keep tabs on who is still using those older versions so that you can communicate with them directly about getting them up to speed with your latest API.
• Be active in any open source communities maintaining libraries for or using your APIs, at least to open issues letting them know the details of upcoming changes.

For those of us shouting “Hypermedia! Hypermedia!” as an alternative to versioning, or at least as a helpful hand in the process: yes, the goal of hypermedia and RESTful architecture is to allow systems to evolve after they are already deployed gracefully, so that the API exposes new behaviours through hypermedia and clients execute this on the fly. This would be awesome – if our clients are actually written to consume hypermedia like this. But the fact is, most clients aren’t, and even if hypermedia practices were mainstream, if you have an open API, you have no clue who your consumers are and/or how they’re consuming your API. If you make changes to a resource and expect hypermedia clients to be able to keep up, you’re ignoring any devs out there who might not be using hypermedia clients. If you communicate about these changes in advance, at least those folks will have a chance to prepare and catch up.

The Ugly Truth

You’re never going to keep all of your API consumers happy:

you’re going to break things, you’re going to expect they consume your API in specific ways or for specific purposes, and you’re going to be wrong. The only way to minimize breakage and maintain happiness in your community is transparency and proactive communication.

 

Part of this specific post if been borrowed by Shelby Switzer where you can find the original here.