GraphQL

Building GraphQL API with Python & Django Part #4: Mutations

In this post, we will learn how to write GraphQL mutations to manipulate the data at server

Founder @ednsquare | Continiously Designing Testing Coding at ednsquare | Any query? shoot an email at ednsquare@gmail.com

Published · Apr 21 2020

Previous tutorial:Building GraphQL API with Python & Django Part #3: Queries

Starting boilerplate code for this chapter can be found Github

The process of sending data to the server is called a mutation. Defining it is pretty similar to how you’ve defined the query.

 In this section, you’ll learn how to add a mutation to the GraphQL API. This mutation will allow you to post new Human character to the server.  In this tutorial, we will learn
How to write a mutation
We will add mutation to create Human object
We will add mutation to update Human object
We will add mutation to delete Human object
  
Let's get started!!
. . .
Extending the schema definition
We will add mutations to manipulate the Human object. In general, when adding a new feature to the API, the process will look pretty similar every time:
Extend the GraphQL schema definition with a new root field ( in our case it will be mutation)
Implement corresponding resolver functions for the added fields ( mutation )  

This process is also referred to as schema-driven or schema-first development. So, let’s go ahead and tackle the first step, extending the GraphQL schema definition.
. . .
Adding createHuman Mutation
Let’s start by implementing a createHuman mutation that allows you to post a new Human character to the server, first, we will be adding proper fields to accept the mutation, then we will add the resolver function to resolve the mutation

1. Define Schema
So, let’s go ahead and tackle the first step, extending the GraphQL schema definition by adding the createHuman  mutation.
# python-graphql-part-4/after/pythonSWAPI/swapi/schema.py

#1
class Mutation(graphene.ObjectType):
    #2
    create_human = graphene.Field(
        #3
        HumanType, 
        #4
        id=graphene.NonNull(graphene.Int),
        name=graphene.NonNull(graphene.String),
        gender = graphene.NonNull(Gender),
        birth_year = graphene.NonNull(graphene.String),
        mass = graphene.Int(),
        height = graphene.Int(),
        home_planet = graphene.String()
    )
    def resolve_create_human(self, info, id, name, gender, birth_year, mass, height, home_planet):
        return resolver_create_human(id, name, gender, birth_year, mass, height, home_planet)

Let's walk through the comments to understand the code:
First we have defined our root Mutation
We have defined the createHuman mutation that creates a new Human character
We have defined the return type of cerateHuman mutation
We have defined the list of arguments which are required by the createHuman mutation

2. Implement resolver functions
The next step is to implement the resolver function for the createHuman mutation. In fact, one thing we haven’t mentioned yet is that not only root fields, but virtually all fields on the types in a GraphQL schema have resolver functions.
# python-graphql-part-4/after/pythonSWAPI/swapi/schema.py

class Mutation(graphene.ObjectType):
    create_human = graphene.Field(
        HumanType, 
        id=graphene.NonNull(graphene.Int),
        ... more input fields    
    )
    #1
    def resolve_create_human(self, info, id, name, gender, birth_year, mass, height, home_planet):
      #2  
      return resolver_create_human(id, name, gender, birth_year, mass, height, home_planet)

Let’s walk through the numbered comments again:
We have added the resolver function to resolve the mutation, it receives input fields as arguments, passed by the use while calling createHuman mutation
We have implemented the helper function that accepts the input arguments and creates a new human character

You can look at the implementation of the helper function that creates a new Human object into the database and returns the same
# python-graphql-part-4/after/pythonSWAPI/swapi/resolvers.py

def resolver_create_human(id, name, gender, birth_year, mass, height, home_planet):
    return Human.objects.create(
        id=id,
        name=name, 
        gender=gender, 
        birth_year=birth_year, 
        mass=mass, 
        height=height, 
        home_planet=home_planet
    )

Go ahead and test the implementation by navigate to http://localhost:8080in your browser. 

If you expand the documentation of the Playground, you’ll notice that another mutation called createHuman  is now available.

  
Now its time to test our mutation to see it in action!
. . .
Testing the mutation
Go ahead and restart your server so you can test the new API operations. Here is a sample mutation you can send through the Playground:
mutation {
  createHuman(
    id: 6, 
    name: "R2-D2", 
    gender: UNKNOWN, 
    birthYear: "CC-129BB", 
    mass: 100, 
    height: 85, 
    homePlanet: "Tatoonie"
  ) {
    id
    name
    gender
    homePlanet
    birthYear
    mass
    height
  }
}

The server response will look as follows, it will return the newly create Human object:
{
  "data": {
    "createHuman": {
      "id": 6,
      "name": "R2-D2",
      "gender": "UNKNOWN",
      "homePlanet": "Tatoonie",
      "birthYear": "CC-129BB",
      "mass": 100,
      "height": 85
    }
  }
}

To verify that your mutation worked, you can send the Humans query from before again - it now returns the additional  Human that you created with the mutation:

  
We have stored the Humans data into the SQLite database, so it will persist after the server restarted.
. . .
Update/Delete human Mutation
The way we have implemented the createHuman mutation, we can also implement the create or update human mutation, as you can see in below image we also have two more mutations to update and delete the human object

A mutation to update Human object

  
A mutation to delete human object:
 
  
You can play around with these mutations to manipulate the Human objects stored at the GraphQL server
. . .
In the next tutorial, we will learn how to handle the GraphQL errors into our Application.

Up next: Building GraphQL API with Python & Django Part #5: GraphQL Errors

Final code for this chapter can be found Github