Add mutations and input type

Author: Sashko Stubailo

site/docs/Learn-Queries.md

@@ -186,31 +186,30 @@ Here's an example of a simple mutation:
 ```graphql
 mutation CreateCharacterInEpisode($name: String!, $appearsIn: Episode!) {
   createCharacter(name: $name)
-  addCharacterToEpisode(name: $name, episode: $appearsIn)
 }
 ```
 
-You can see that a mutation can contain multiple fields, just like a query. There's one important distinction between queries, and mutations, other than the name:
-
-**While query fields are executed in parallel, mutation fields run in series, one after the other.**
-
-This means that even though we sent `createCharacter` and `addCharacterToEpisode` in one request, the first is guaranteed to finish before the second begins, ensuring that we create the character before trying to add it an episode.
-
 #### Returning data from mutations
 
-Just like in queries, you can ask for nested fields in the mutation result. This can be useful for fetching the new state of an object after an update:
+Just like in queries, if the mutation field returns an object type, you can ask for nested fields. This can be useful for fetching the new state of an object after an update:
 
 ```graphql
-mutation IncrementCredits($characterId: ID!) {
-  incrementCredits(characterId: $characterId) {
+mutation IncrementCredits($humanId: ID!) {
+  incrementCredits(humanId: $humanId) {
     totalCredits
   }
 }
 ```
 
-In this case, the `incrementCredits` mutation field returns a `Character` object, so we can query the new value of `totalCredits` after giving that character some more credits. Otherwise, we would have needed to send two requests - one to update the credits, and another to get the new value - or guess at the new amount based on outdated data.
+In this case, the `incrementCredits` mutation field returns a `Human` object, so we can query the new value of `totalCredits` after giving that character some more credits. Otherwise, we would have needed to send two requests - one to update the credits, and another to get the new value - or guess at the new amount based on outdated data.
+
+#### Multiple fields in mutations
+
+A mutation can contain multiple fields, just like a query. There's one important distinction between queries and mutations, other than the name:
+
+**While query fields are executed in parallel, mutation fields run in series, one after the other.**
 
-That's all! Now you know everything you need to know about GraphQL queries and mutations to build a pretty good application. For more advanced features and tips, check out the advanced section.
+This means that if we send two `incrementCredits` mutations in one request, the first is guaranteed to finish before the second begins, ensuring that we don't end up with a race condition with ourselves.
 
 ### Fragments and type conditions
 

site/docs/_swapiSchema.js

@@ -24,7 +24,12 @@ schema {
 
 type Query {
   hero(episode: Episode): Character
-  search(query: String): [SearchResult]
+  search(text: String): [SearchResult]
+}
+
+type Mutation {
+  createHuman(human: HumanInput!): ID!
+  incrementCredits(humanId: ID!): Human
 }
 
 # The episodes in the Star Wars trilogy
@@ -70,6 +75,9 @@ type Human implements Character {
 
   # A list of starships this person has piloted, or an empty list if none
   starships: [Starship]
+
+  # The number of credits this human has
+  totalCredits: Int
 }
 
 # An autonomous mechanical character in the Star Wars universe
@@ -90,6 +98,15 @@ type Droid implements Character {
   primaryFunction: String
 }
 
+# The object to be passed in when creating a new human
+input HumanInput {
+  # The name of the new human
+  name: String!
+
+  # The movies this human appears in
+  appearsIn: [Episode]!
+}
+
 # Units of length
 enum LengthUnit {
   # The standard unit around the world