GraphQL

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

In this tutorial we will learn how to create the Types in GraphQL and how to resolve the GraphQL Query

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

Published · Apr 20 2020

Previous tutorial: Building GraphQL API with Python & Django Part #2: Setting up Server & Schema

Starting boilerplate code for this chapter can be found Github

In this section, you are going to implement the first API operation that provides the functionality for a Star Wars API, We will add wars character Human.
In this tutorial, we will learn: 
How to define a type in GraphQL
How to get the list of all the humans
How to get Human by ID

  
Another essential decision is about the database. Django works out of the box with SQLite – a file-based database – which you will use. On production systems, you should have a more robust database, such as PostgreSQL.
. . .
Defining The Django Models
Before we start with the actual implementation of GraphQL API, we need to define the model to save and query data from the database, for this tutorial we will be using the SQLite, let's go ahead and create the Human model:
# python-graphql-part-3/after/pythonSWAPI/swapi/models.py

from django.db import models

class Human(models.Model):
    id = models.IntegerField(primary_key=True, unique=True)
    name = models.CharField(max_length=1024)
    gender = models.IntegerField()
    height = models.IntegerField()
    birth_year = models.CharField(max_length=1024)
    mass = models.IntegerField()
    home_planet = models.CharField(max_length=1024)

    def __str__(self):
        return self.name
  
Once we have defined our models, Don’t forget to create & run migrations:
python manage.py makemigrations 
python manage.py migrate

Now is a good time to load up some test data. The easiest option will be to add data into JSON file, you see the JSON file here. You can then run the following command to add the JSON objects into the database:
$ python ./manage.py loaddata humans.json
Installed 4 object(s) from 1 fixture(s)
. . .
Extending the schema definition
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 (and new data types, if needed)
Implement corresponding resolver functions for the added fields

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.

A ) Query: Get List of  All Humans
Let’s start by implementing a humans query that allows you to retrieve a list of star wars Human elements. 

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

class Gender(graphene.Enum):
    UNKNOWN = 0
    MALE = 1
    FEMALE = 2
    HERMAPHRODITE = 3

class HumanType(graphene.ObjectType):
    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()

Pretty straightforward. You’re defining a new Human that represents a Human of star wars. Each HumanType has an id, a name homePlanet planet.  Gender is the enum type which represents the gender.

You’re then adding another root field to the Query type that allows you to retrieve a list of Human elements. 

2. Implement resolver functions
The next step is to implement the resolver function for the humans query. 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.

You’re adding a new resolver for the feed root field. Notice that a resolver always has to be named after the corresponding field from the schema definition.
# python-graphql-part-3/after/pythonSWAPI/swapi/schema.py

#1
class Query(graphene.ObjectType):
    #2
    humans = graphene.List(HumanType)
    #3  
    def resolve_humans(self, info):
        return resolver_humans()

 Let's walk through the comments to understand the code:
We have defined the root schema query
We have added the humans query which returns the List of Humans
We have defined the resolver function for the humans query, note the definition of humans resolver, it's prefixed with the resolve_ keyword. Its resolvers the query and returns the result

Below is the definition of helper function which returns the list of human characters:
# python-graphql-part-3/after/pythonSWAPI/swapi/resolvers.py

from swapi.models import Human

def resolver_humans():
    return Human.objects.all()

Go ahead and test the implementation, If you expand the documentation of the Playground, you’ll notice that another query called humans is now available:

  
Try it out by sending the following query:
{
  humans {
    id
    name
    height
    mass
    homePlanet
  	gender
  }
}

Awesome, the server responds with the data you defined in Human:
{
  "data": {
    "humans": [
      {
        "id": 1,
        "name": "Luke Skywalker",
        "height": 172,
        "mass": 77,
        "homePlanet": "Tatooine",
        "gender": "MALE"
      },
      {
        "id": 2,
        "name": "C-3PO",
        "height": 167,
        "mass": 75,
        "homePlanet": "Tatooine",
        "gender": "UNKNOWN"
      },
      {
        "id": 3,
        "name": "R2-D2",
        "height": 96,
        "mass": 32,
        "homePlanet": "Naboo",
        "gender": "UNKNOWN"
      },
      {
        "id": 4,
        "name": "Darth Vader",
        "height": 202,
        "mass": 136,
        "homePlanet": "Tatooine",
        "gender": "MALE"
      },
      {
        "id": 5,
        "name": "Leia Organa",
        "height": 150,
        "mass": 49,
        "homePlanet": "Alderaan",
        "gender": "FEMALE"
      }
    ]
  }
}

Feel free to play around with the query by removing any fields from the selection set and observe the responses sent by the server.
. . .
B ) Query: Get Human by ID
We will pass the human ID into the resolver function and it should return the appropriate Human, let's write some code

1. Define Schema
We will use the same schema previously defined for the HymanType
# python-graphql-part-3/after/pythonSWAPI/swapi/types.py

class HumanType(graphene.ObjectType):
    id = graphene.NonNull(graphene.Int)
    name = graphene.NonNull(graphene.String)
    ... more fields

2. Implement resolver functions
The next step is to implement the resolver function for the human query. It will accept the human id as parameter
# python-graphql-part-3/after/pythonSWAPI/swapi/schema.py

#1
class Query(graphene.ObjectType):
    #2
    human = graphene.Field(
        HumanType, 
        #3
        id=graphene.NonNull(graphene.Int)
    )
    #4
    def resolve_human(self, info, id):
        return resolver_human(id=id)

Let's walk through the comments to understand
We have defined the root query
We have added the human query which returns the human
We have added the arguments required by the query, we are accepting the human id as arguments and it can not be empty
We have implemented the resolver function to resolve the human query

Go ahead and test the implementation, If you expand the documentation of the Playground, you’ll notice that another query called human is now available:

  
Try it out by sending the following query:
{
  human(id: 1) {
    id
    name
    height
    mass
    homePlanet
  	gender
  }
}

Awesome, the server responds with the data you defined in Human:
{
  "data": {
    "human": {
      "id": 1,
      "name": "Luke Skywalker",
      "height": 172,
      "mass": 77,
      "homePlanet": "Tatooine",
      "gender": "MALE"
    }
  }
}

Feel free to play around with the query by removing any fields from the selection set and observe the responses sent by the server. Now you can query the human by ID
. . .
In the next tutorial, we will learn how to write the mutation to crate and update the existing human data on the server.

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

Final code for this chapter can be found Github