How Should We Version GraphQL APIs?

graphql.org

API Versioning is Never Fun

Versioning GraphQL is Possible

https://help.shopify.com/en/api/versioning#the-api-version-release-schedule

Continuous Evolution

Commitment to Contracts

  • 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

Communicate 💌

  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 🔎

Last Resort 🚨

{ "errors": [ { "message": "Deprecated: Field `name` does not exist on type `User` anymore. Upgrade as soon as possible. See: https://my.api.com/blog/deprecation-of-name-on-user" } ] }

So… Should we Version?

--

--

--

#GraphQL Enthusiast, Speaker, Senior Software Developer @ Netflix 📖 Book is now available https://book.productionreadygraphql.com/

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Topaz Denoise 6 Serial Key

Introducing Hulu’s Modern Web Stack

Code for All Newsletter — July 2020

Free Scanner Radio Pro — Fire and Police Scanner

Free Scanner Radio Pro - Fire and Police Scanner

My style.CSS

CSR Tale #3: The paper that took 10 years to publish!

To Retain Or Not To Retain

Teachable, Thinkific, or Udemy? Which is the Best Platform for Online Course Creators?

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 https://book.productionreadygraphql.com/

More from Medium

Generate your Apollo DataSources

Choosing the right data type & means of generating unique primary keys

SemVer versioning

JS monorepos in prod 7: Continuous Integration and Continuous Deployment with GitHub Actions