It’s been awhile since I’ve blogged, mostly because I haven’t taken the time to sit down and write. Over the past few weeks I’ve been inspired by Marc-André and Julia to write a little something. I like their approach of blogging as a way of taking notes and sharing things they’ve learned.
Coincidentally, I’ve been learning a lot about GraphQL over the past few months and wanted to share my excitement for it.
Setting aside the advantages normally brought up when talking about transitioning from REST to GraphQL, there is one point that really stuck to me: knowing what the API client is actually using.
Like many companies, Shopify has a REST API that third party app developers use to extend Shopify’s functionality.
Many years ago, we made the conscious decision of not versioning our REST API. Instead, we try to evolve our API without introducing breaking changes along the way. If one needs to be made, we resort to deprecating the functionality for X months, letting app developers know, and finally gracefully removing the functionality.
By making it hard (but not impossible) for us to make breaking changes to our API, it forces us to think twice as much when building new features.
Deprecating an end-point is easy as we can monitor request logs, notify only the subset of our app developers that are actively using it, and remove the end-point once it is no longer used.
What isn’t so easy is deprecating a specific attribute contained in the response payload of an end-point. We know who is using the end-point, but out of that subset, we don’t know who is using that specific attribute. There also isn’t a convention in REST for letting clients know that a specific attribute is deprecated.
Knowing what API clients are requesting is straight forward as the basis of GraphQL is letting the client decide exactly what they want to get back.
An operation selects the set of information it needs, and will receive exactly that information and nothing more, avoiding over‐fetching and under‐fetching data.
By instrumenting field usage in our GraphQL API, we can easily look up the usage of certain types and fields within a given interval.
As an extra bonus, the concept of deprecations is built-in to GraphQL. You can easily mark a field or enum value as deprecated in your GraphQL schema and it is expected that tools report this information back to the developer using the tool.
To support the management of backwards compatibility, GraphQL fields and enum values can indicate whether or not they are deprecated (
isDeprecated: Boolean) and a description of why it is deprecated (
Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer‐facing warnings.
While there are many other things that I’m excited about in GraphQL, these are the two that I don’t think we talk enough about and which will make our lives easier.