Give mutation its own section and nested mutations

[emilebosch]

Ok sorry for the last one, that was messy and a bit too hasty.
Here a second attempt to get these docs in order.

In this PR i propose:

• Give mutations its own spot in schema
• Add nested mutations syntax for embedding

[xuorig]

Maybe have better wording for this since this seems to imply Nested Mutation in the sense of (not in spec):

myMutation(input: {...}) {
  myNestedMutation(input: {...}) {
     ...
  }
}

and not nested inputs?

[rmosolgo]

Yes, I was confused by this too. I thought that "nested mutations" referred to this:

graphql/graphql-spec#252

(Which is the same as the example posted above.)

I would have described this as "mutations with complex inputs". However, I may be wrong to think that since at least the Graph.cool folks have called this "nested mutations": https://blog.graph.cool/improving-dx-with-nested-mutations-af7711113d6#.syi1rk3o8

[xuorig]

Graph.cool folks have called this "nested mutations"

Interesting 🤔 im not convinced of the wording

[rmosolgo]

Me either, but it wouldn't be the first time that my perspective as a graphql implementer was off track of the rest of the community 😖

[emilebosch]

I agree that they are not nested mutations but embedded inputs or complex input. Please let me know so i can adjust accordingly!

[emilebosch]

The use case would be that whenever creating items in bulk this really helps.
An added benefit of this is that it allows you to to easily wrap it in an transaction, when creating multiple records, making a mutation transaction safe. Which is for what i was using it in the first place.

Is that something that we should maybe mention? I.e. with ruby sample code? I know graphql is db agnostic, but still graphql/activerecord is a common use case.

[emilebosch]

Fixed the naming to nested input types :)

[Willianvdv]

Copy suggestion:

Let's create a mutation that adds multiple todo items at once

[Willianvdv]

Have you considered making a nested mutation input type that creates multiple post items? The example above already defines the type so it might be easier for the reader to continue with this example set.

[rmosolgo]

Sorry for the slow response on this one, thanks, it looks great!

[rmosolgo]

Published 🎉 http://rmosolgo.github.io/graphql-ruby/schema/mutations