How Should We Version GraphQL APIs?

API Versioning is Never Fun

In API Versioning Has No “Right Way”, Phil Sturgeon does a very useful tour of API versioning techniques we’ve been seeing in the wild. The conclusion Phil ends up is one I share. No versioning approach is bullet proof, and most of them are quite 💩 for clients.

Versioning GraphQL is Possible

Nothing is stopping anyone from versioning a GraphQL API. The spirit of Lee Byron won’t come haunt you if that happens (Actually, I can’t promise that 👻). In fact, Shopify recently adopted a URL versioning approach to evolve their GraphQL API.

Continuous Evolution

The alternative to versioning, as mentioned at the beginning of this post is to simply not do it. The process of maintaining a single version and constantly evolving it in place rather than cutting new versions is often called Continuous Evolution. One of my favorite way to describe the philosophy comes from Phil Sturgeon:

Commitment to Contracts

Ironically, I remember hearing that Tobi was absolutely against API versions back when I worked at Shopify. Back then I was shocked to hear that, and was really skeptical. The funny thing is now I totally understand where Tobi was coming from, and I hold similar views nowadays.

  • Security Changes: You realize a field has been leaking private data or that you should never expose a certain set of fields.
  • Performance issues linked to the API design: A unpaginated list that can potentially return millions of records, causing timeouts and breaking clients.
  • Authentication changes: An API provider deciding to deprecate “basic auth” all together, forcing API clients to move towards JWTs.
  • A non-null field actually can be null at runtime: I would not wish this one on my worst enemy.

Change Management

As API maintainers, no matter what evolution / versioning process we decide to standardize one, one thing is for sure: we have to get good at change management. Rarely will throwing a deprecated directive on a field solve all your problems. We need more a bit more than this!

Communicate 💌

Communicate early and often. Reaching all users of the use case you are deprecating is hard. Often, a combination of all mediums you can think of works best:

  1. An API upcoming change log.
  2. Your API’s Twitter Account.
  3. A notice on your developers doc website.
  4. A blog post announcing the upcoming changes.
  5. A notice on the API client dashboard if you have one.
  6. Direct Email.

Track 🔎

The best communication is often the one that is targeted and closer to individual integrators. But for that to happen you need to know in the first place who out of all integrators could be affected. For GraphQL APIs, it’s both easier and harder than with HTTP APIs. Let’s start with the good news. As I mentioned in this article, GraphQL allows us to track our API usage in a very fine grained way, which is awesome. The bad news is that doing that requires a bit more work than simply looking at HTTP logs or tracking endpoints.

Last Resort 🚨

Sometimes you’ve announced the change everywhere, reached out to individual integrators via email, and still there’s usage. There will always be a point where a tradeoff needs to be made between how perfect the transition needs to be, and evolution not being blocked.

{ "errors": [ { "message": "Deprecated: Field `name` does not exist on type `User` anymore. Upgrade as soon as possible. See:" } ] }

So… Should we Version?

That decision ultimately boils down to your own set of trade offs, what your clients are expecting, and what kind of expectations you want to set as an API provider. However, more and more, I’m starting to think that versioning usually ends up causing more trouble than anything, since a lot of the time, there comes a point where changes need to be made, just like in a continuous evolution approach.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Marc-André Giroux

Marc-André Giroux

#GraphQL Enthusiast, Speaker, Senior Software Developer @ Netflix 📖 Book is now available