GraphQL Mutation Design: Hypermedia GraphQL API

State Transitions with Mutations

A lot of APIs offer a way to move a resource / object through a set of transitions. For example, with our e-commerce example, we might want to move a checkout from a “Cart”, to “Checking Out”, to “Payment”, and finally “Order”.

Hypermedia Mutations?

What if we took this actions field and tried to apply it somehow to GraphQL 🤔 Let’s focus on mutations for now.

An example CheckoutCreatePayload Type, which provides a `__actions` field.
Mutation Operation
Mutation Response

What now

I’m really interested to see if we could come up with something like this for GraphQL. I’m hesitant if this should somehow eventually be part of the spec, or “a spec” outside of the GraphQL original one. Maybe even just a “best practice” 🤷‍♂️


Ivan Babak shared a good concern in one of the comments that I wanted to address here:

  1. They make our API more explorable. Even if you’re building a UI by hand, chances are you will be trying out a mutation, or a REST endpoint. Instead of looking through the docs or tutorials, you’ll be guided through the next state transition, and get a mental model of the API quicker.
  2. Documentation in Schema. Just like you could say descriptions are useless on the introspection schema, since they require a human to read them, having well documented transitions / actions allows someone to understand the flow of the API quicker.
  3. They make Schema Evolution / API evolution easier if clients follow these links. The mutation or endpoint to call for a transition can change and clients simply follow this link.
  4. For REST APIs especially, they remove the need for dynamically built hrefs, IDs and variables. We could apply the same to GraphQL as well depending on scenarios.
  5. Bonus random idea: They would probably make schema stiching and the likes really fun to use also if you included URIs.



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