Building a Python API with GraphQL, Falcon and Graphene

 

      Photo by Matt Duncan on Unsplash

GraphQL is a data query language for your API, and a server-side runtime for executing queries using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

Today we will build a GraphQL server using:

• Python 3.11.3
• Falcon
• SQLAlchemy
• Graphene
• PostgreSQL
• Dependency Injection
• Ariadne

Our article is heavily based on this excellent example. 

Falcon is a minimalist ASGI/WSGI framework for building APIs and microservices. We will also be using Gunicorn with Uvicorn as the app server. And Graphene is a library for building GraphQL schemas/types fast and easily. 

Let's dig directly into our example! We'll create a GraphQL server to query information about music bands, their genre and their members. 

The ERD shows some simple relations: a musical band has its members, it has a musical genre and each member plays an instrument (for the sake of the example, lets limit that relation to just one instrument).

You will find the code of this article on my Github repository

Prerequisites

Before getting started, you need to have the following installed:

• Python (I used 3.11.3)
• PostgreSQL
• Pip (Python Package manager)

Setup

After cloning the repo, go to the directory and create your virtual environment:

python3 -m venv venv
source venv/bin/activate

You can install the required packages by running: 

pip install -r requirements.txt

Define the Data Model

As I said before, we will be using SQLAlchemy to define our data model. Here's the definition of our models:  

Connect to the Database

Next, you need to create a connection to the DB and a session to run queries

Define the GraphQL Schema

Now we need to define the GraphQL schema for our API

 getMusicalBandsInformation  is the name of the query we will be using to get the band information. Now here's where things start to get interesting: Ariadne uses dedicated objects to query, then it will map 'resolvers' to fields in Query type using decorator syntax. This enable frontend and backend teams to cooperate effectively: the same types used by the backend to expose the information can be used by the frontend to show it in the UI. 

Here's our 'band' resolver:

Finally, the service which the resolver will call: this guy is in charge of querying the DB (using SQLAlchemy) to get the information and transform the result into a type needed by GraphQL for output.

 

Create the API

We can create now the API using Falcon. This will be done inside api.py and server.py:

The code inside these 2 classes is minimalist.

Test the API

To start the API just run:

make start-app

This will start the API server with Gunicorn (with a Uvicorn worker) at  http://localhost:80

Then let's call our query. At its simplest GraphQL is about asking for specific fields on objects:

{

  h query {

        getMusicalBandsInformation(

        # Queries can have comments!

            item: { bandName: "Muse" } 

        )

        {

          bandId,

          name

        } 

     }

}

  }

)

  }

}

{

  " "data": {

        "getMusicalBandsInformation": {

               "bandId": 2,

               "name": "Muse"

        }

    }

  }

}

You can see immediately that the query has exactly the same shape as the result. This is essential to GraphQL, because you always get back what you expect and the server knows exactly what fields the client is asking for. 

Here we simply ask the name of the band, which is a String type. 

Oh, one more thing - the query above is interactive. That means you can change it as you like and see the new result. Try adding an genre field to the object in the query, and see the new result.

In the previous example we just asked for the name of the band and the id in the DB, but fields can also refer to Objects. In that case you can make a sub-selection of fields for that object. GraphQL can traverse related objects and their fields, letting clients fetch lots of related data in one request, instead of making several roundtrips as one would need in a classic REST architecture. 

 

  h  query {

        getMusicalBandsInformation(

            item: { bandName: "Muse }

        )

        {   

          bandId,

          name,

          genre, 

sd.       bandMembers {

              firstName,

              familyName,

              instrument

          }

        }

    }

  }

}

{

    "data": {

        "getMusicalBandsInformation": {

          "bandId": "2", 

"         "name": "Muse",
         "genre": "Metal", 
         "bandMembers": [
             {
               "firstName": "Mat",
               "lastName": "Bellamy",
"              "instrument": "guitar", 
             },
            {
               "firstName": "Dominic",
               "lastName": "Howard",
"              "instrument": "drums", 
             },
            {
               "firstName": "Chris",
               "lastName": "Wolstenholme",
"              "instrument": "bass", 
             } 
          ] 
        }

    }

  }

}

Note that in this example, the bandMembers field returns an array of items. GraphQL queries look the same for both single items or lists of items. However, we know which one to expect based on what is indicated in the schema.

You can now imagine all the possibilities you can design based on the needs of your project.

I hope this tutorial helps you get started with GraphQL, Python, Falcon and SqlAlchemy.

Thanks for reading and don't forget to give a like to the article!

Again, here is my Github repository

sources:

https://github.com/alecrasmussen/falcon-graphql-server

https://medium.com/swlh/graphql-for-the-beginner-pythonistas-e62bf2433434

https://towardsdatascience.com/connecting-to-a-graphql-api-using-python-246dda927840

https://graphql.org/learn/

https://medium.com/@ryk.kiel/graphql-and-fastapi-the-ultimate-combination-for-building-apis-with-python-f4391bf5505c