GraphQL Mutation design guidelines regarding layout and return values

[SquireOfSoftware]

Sup all,

I had a question regarding the design of GraphQL mutations.

I have been doing some digging around:

• https://www.apollographql.com/blog/graphql/basics/mutation-vs-query-when-to-use-graphql-mutation/ <-- Apollo notes on mutations
• https://api.spacex.land/graphql/ <-- SpaceX mutations
• https://docs.github.com/en/enterprise-server@3.4/graphql/guides/forming-calls-with-graphql#example-mutation <-- Github GrpahQL
• https://blog.developer.atlassian.com/bringing-you-new-confluence-graphql-apis-in-beta/ <-- Atlassian mutations
• https://shopify.dev/apps/tools/graphiql-admin-api <-- Shopify mutation queries
• https://www.freecodecamp.org/news/beware-of-graphql-nested-mutations-9cdb84e062b5/ <-- a warning on nested mutations

My questions are:

1. Why do people go with flat mutations?
2. Is it best practice to duplicate the mutation schema to match that of the query schema?

1. Flat mutations vs hierarchical mutations

Like a lot of mutation designs are like:

createThing(input: ThingCreationInput)

Like of the links above, only a few organisations went with something like:

concept {
  createThing(input: ThingCreationInput) {
    ...
  }
}

Is there a reason why you would prefer a flattened mutation over a nested one?

Surely you could do something like this right?

concept(first: 10) {
  createThing(input: ThingCreationInput) {
    ...
  }
}

Which would be, for the first 10 concepts, create a thing under them.

Is the flattened mutation model easier to process? Or faster? Or is it because mutations are still fairly new?

Is it because you have search operations which make nested mutations redundant?

Or have a misunderstood the intention of mutations?

2. Mutation schema layout

I have noticed a common pattern mainly spurned by this blog post: https://www.apollographql.com/blog/graphql/basics/designing-graphql-mutations/

That talks about two concepts:

• Naming your mutations nounVerb vs verbNoun
• Hiding your inputs and response payloads behind variables

My question is related to the second point, which is: Should you effectively copy your query schema?

So let us say we have something like:

type Ball {
  id: ID!
  name: String
  type: String!
}

schema {
  mutation: Mutation
  query: Query
}

type Query {
  ball(id: Int, type: String): Ball
}

type Mutation {
  createBall(input: BallInput): ? # should this be BallPayload or should this just be Ball?
}

input BallInput {
  name: String
  type: String
}

Should the createBall mutation have a type of BallPayload or just a Ball?

I guess if you have nested mutations, like say you wanted to create the ball and then edit some attribute of the ball then you could do something like:

type Mutation {
  createBall(input: BallInput): BallPayload
}

type BallPayload {
  updateName(input: String): Ball!
}

mutation createAndUpdateBall {
  createBall(input: BallInput) {
    updateName(input: "Basket") {
      name
    }
  }
}

Or is it better to return BallPayload with all of the attributes that hang off it like so:

type Mutation {
  createBall(input: BallInput): BallPayload
}

type BallPayload {
  id: ID!
  name: String
  updateName(input: String): BallPayload!
}

mutation createAndUpdateBall {
  createBall(input: BallInput) {
    updateName(input: "Basket") {
      name
    }
  }
}

And then have the mutation inside the BallPayload entity? like a builder?...after thinking about this...perhaps this might be a bad idea since you have to filter out certain parts of the schema out...

I feel like I am stepping into some unknown areas here.

[benjie]

Why do people go with flat mutations?

In the GraphQL spec, only selections over the Mutation type (assuming you're using the default operation type names) is executed in serial; all other selection sets are executed in parallel. It's unsafe to run mutations in parallel - very likely to lead to race conditions and the like - so mutations should be done only in the root selection set of a mutation operation, at least for now.

Should the createBall mutation have a type of BallPayload or just a Ball?

You can do either, the reason that we tend to use BallPayload rather than Ball is that it allows for expanding the schema later (this can also apply to why connections are often used over lists even when cursor pagination is not necessary) - GraphQL is big on versionless schemas, so leaving yourself space for additions is nice. For example, imagine your business logic changed and now the createBall mutation "costs" the user some kind of credits. It would be handy if the mutation payload were to not only tell you about the ball that was created, but also about your remainingCredits or similar. Note, however, that your BallPayload is misguided; instead of duplicating all the properties from ball it should reference the ball type:

type BallPayload {
  ball: Ball
  # space here to expand your API in future, e.g.:
  # remainingCredits: Int
}
type Mutation {
  createBall(...): BallPayload
}

---

You may be interested in #252

[SquireOfSoftware]

Ah gotcha, thanks for the response!