schema-design: Address mutation and mutation response feedback.

abernix · abernix · commit fc187b53f514 · 2018-05-31T16:38:54.000+03:00
diff --git a/docs/source/guides/schema-design.md b/docs/source/guides/schema-design.md
@@ -140,7 +140,7 @@ query GetBooks {
 
 The `Mutation` type is a core type in GraphQL which specializes in _modifying_ data, which contrasts the `Query` type used for _fetching_ data.
 
-Unlike REST, where the behavior is more ad-hoc, the `Mutation` type is designed with the expectation that there will be a response object.  This ensures that the client receives the most current data without a subsequent round-trip re-query.
+Unlike REST, where the behavior can be more ad-hoc, the `Mutation` type is designed with the expectation that there will be a response object.  This ensures that the client receives the most current data without a subsequent round-trip re-query.
 
 A mutation for updating the age of a `User` might look like this:
 
@@ -182,44 +182,21 @@ Once executed by the server, the response returned to the client might be:
 }
 ```
 
-The first thing to note is that it’s most common to return the thing you’re updating from a mutation. In our example, we were updating a `User` record, so we returned that updated user. There’s nothing _enforcing_ this practice, but it’s highly recommended, because it’s often needed to have an updated user to let the clients update any local cache with a new instance of that `User`. For this same reason, it’s useful design mutations to update only one entity. If you wanted to update two unrelated entities, it’s recommended to in separate mutations. For more details on how to handle errors and warnings in mutations, see the [mutation responses](#mutation-responses) section below.
+While it's not mandatory to return the object which has been updated, the inclusion of the updated information allows the client to confidently update its local state without performing additional requests.
 
-But what if we wanted to update more than just a single or couple attributes on a user? Passing each thing we need as a single argument would get tedious. Especially if multiple mutations used similar fields. For this, we can use input types, which are explained in the next section.
+As with queries, it's best to design mutations with the client in mind and in response to a user's action.  In simple cases, this might only result in changes to a single document, however in many cases there will be updates to multiple documents in different collections, for example, a `likePost` mutation might update the total likes for a user as well as their post.
 
-<h3 id="mutation-input-types">Input types</h3>
-
-Input types are a special type in GraphQL which are defined as arguments to queries and, more commonly, mutations.  They can be thought of as object types for arguments, in addition to the other scalar types.  Input types are especially useful when multiple mutations require similar information; for example, when creating a user and updating a user require the same fields, like `age` and `name`.
+In order to provide a consistent shape of response data, we recommend adopting a pattern which returns a standardized response format which supports returning any number of documents from each collection which was modified.  We'll outline a recommended patterns for this in the next section.
 
-Input types are used like any other type and defining them is similar to a typical object type definitions, but with the `input` keyword rather than `type`.
-
-Here is an example of two mutations that operate on a `User`, _without_ using input types:
-
-```
-type Mutation {
-  createUser(name: String, age: Int, address: String, phone: String): User
-  updateUser(id: ID!, name: String, age: Int, address: String, phone: String): User
-}
-```
-
-To avoid the repetition of argument fields, this can be refactored to use an input type, as follows:
+<h3 id="mutation-responses">Responses</h3>
 
-```
-type Mutation {
-  createUser(user: UserInput): User
-  updateUser(id: ID!, user: UserInput): User
-}
+GraphQL mutations can return any information the developer wishes, but designing mutation responses in a consistent and robust structure makes them more approachable by humans and less complicated to traverse in client code.  There are two guiding principles which we have combined into our suggested mutation response structure.
 
-input UserInput {
-  name: String
-  age: Int
-  address: String
-  phone: String
-}
-```
+First, while mutations might only modify a single collection, they often need to touch multiple collections.  It makes sense for this to happen in a single round-trip to the server and this is one of the strengths of GraphQL!  When multiple collections are modified, the client code can benefit from having updated fields returned from each collection and the response format should support that.
 
-<h3 id="mutation-responses">Responses</h3>
+Secondly, mutations have a higher chance of causing errors than queries since they are modifying data.  If only a portion of a mutation update succeeds, whether that is a partial update to a single document's fields or a failed update to an entire document, it's important to convey that information to the client to avoid stale local state on the client.
 
-Mutations have a higher chance of causing errors than queries since they are modifying data.  A common way to handle errors during a mutation is to simply `throw` an error.  While that's fine, throwing an error in the resolver will return an error to the caller and prevent a partial response, which could be useful in the event of a partial update.  Consider the following mutation example, which tries to update a user's `name` and `age`:
+A common way to handle errors during a mutation is to simply `throw` an error.  While that's fine, throwing an error in a resolver will return an error for the entire operation to the caller and prevent a more meaningful response.  Consider the following mutation example, which tries to update a user's `name` and `age`:
 
 ```graphql
 mutation updateUser {
@@ -232,7 +209,7 @@ mutation updateUser {
 
 With validation in place, this mutation might cause an error since the `age` is a negative value.  While it’s possible that the entire operation should be stopped, there’s an opportunity to partially update the user’s record with the new `name` and return the updated record with the `age` left untouched.
 
-Luckily, the powerful structure of GraphQL mutations accommodates this use case and can return transactional information about the update alongside the records which have been changed which enables client-side updates to occur automatically.
+Fortunately, the powerful structure of GraphQL mutations accommodates this use case and can return transactional information about the update alongside the records which have been changed which enables client-side updates to occur automatically.
 
 In order to provide consistency across a schema, we suggest introducing a `MutationResponse` interface which can be implemented on every mutation response in a schema and enables transactional information to be returned in addition to the normal mutation response object.
 
@@ -283,7 +260,71 @@ Let’s break this down, field by field:
 * `message` is a string that is meant to be a human-readable description of the status of the transaction. It is intended to be used in the UI of the product.
 * `user` is added by the implementing type `UpdateUserMutationResponse` to return back the newly created user for the client to use!
 
-Following this pattern for mutations provides detailed information about the data that has changed and feedback on whether the operation was successful or not.  Armed with this information, developers can easily react to failures in the client and fetch the information they need to update their local cache.
+For mutations which have touched multiple collections, this same structure can be used to return updated objects from each collection.  For example, a `likePost` type, which could affect a user's "reputation" and also update the post itself, might implement `MutationResponse` in the following manner:
+
+```graphql
+type LikePostMutationResponse implements MutationResponse {
+  code: String!
+  success: Boolean!
+  message: String!
+  post: Post
+  user: User
+}
+```
+
+In this response type, we've provided the expectation that both the `user` and the `post` would be returned and an actual response to a `likePost` mutation could be:
+
+```json
+{
+  "data": {
+    "likePost": {
+      "code": "200",
+      "success": true,
+      "message": "Thanks!",
+      "post": {
+        "likes": 5040
+      },
+      "user": {
+        "reputation": 11
+      }
+    }
+  }
+}
+```
+
+Following this pattern for mutations provides detailed information about the data that has changed and feedback on whether the operation was successful or not.  Armed with this information, developers can easily react to failures within the client
+
+<h3 id="mutation-input-types">Input types</h3>
+
+Input types are a special type in GraphQL which are defined as arguments to queries and, more commonly, mutations.  They can be thought of as object types for arguments, in addition to the other scalar types.  Input types are especially useful when multiple mutations require similar information; for example, when creating a user and updating a user require the same fields, like `age` and `name`.
+
+Input types are used like any other type and defining them is similar to a typical object type definitions, but with the `input` keyword rather than `type`.
+
+Here is an example of two mutations that operate on a `User`, _without_ using input types:
+
+```
+type Mutation {
+  createUser(name: String, age: Int, address: String, phone: String): User
+  updateUser(id: ID!, name: String, age: Int, address: String, phone: String): User
+}
+```
+
+To avoid the repetition of argument fields, this can be refactored to use an input type, as follows:
+
+```
+type Mutation {
+  createUser(user: UserInput): User
+  updateUser(id: ID!, user: UserInput): User
+}
+
+input UserInput {
+  name: String
+  age: Int
+  address: String
+  phone: String
+}
+```
+
 
 <h2 id="gql">Wrapping documents with `gql`</h2>
 
