No, GraphQL Doesn’t Magically Fix API Versioning. Sorry.
I’ve read many times that “with GraphQL you don’t have to version your APIs” or “GraphQL handles API versioning” or similar statements. That’s not quite true.
Actually it’s not at all true. And if we act like it is, we’ll send our poor client developers swimming into a sea of chaos.
GraphQL does, by defining a formal type system, make it easier to declare what the API is and to determine potentially breaking changes and advertise them to consumers. This is a big plus. But even if you’re using GraphQL, unless your API is dead simple and will rarely change, you do need to worry about versioning.
In this post I’ll dive into some of the API versioning issues I’ve seen and describe how GraphQL helps (or doesn’t). I’m referring here to service APIs — REST and its variants/replacements like GraphQL — not binary APIs.
The most common reason to consider versioning an API is to introduce breaking changes. Adding new features generally doesn’t require breaking changes. Typically we do that only when cleaning up APIs that we want to change or eliminate entirely — technical debt, in other words.
What constitutes a “breaking change”? In general, the term means a change to the API that can cause existing, previously valid API calls to fail. In GraphQL the…
