Installing Strawberry

With Strawberry enabled, we can move to refactoring the schema from schema-first to code-first.

Designing the GraphQL Schema in Strawberry

In the previous chapter, we created a GraphQL schema in a .graphql file.

In this schema, we used most of the GraphQL scalar types the language has to offer, plus our custom types and input types definitions. We also created two queries and a mutation. To appreciate what Strawberry has to offer, let’s port each element of our schema from a plain text schema to Python code.

Types and Enums in Strawberry

To start off we begin with the base types of our GraphQL schema.

For someone new to Python typings, there a lot of things here that need a bit of explanation. Thankfully, Python is expressive enough to not overcomplicate things. Let’s start from the top.

To declare a new GraphQL type in Strawberry we use the @strawberry.type decorator, which goes on top of our dataclasses. Next, each type is declared as a dataclass, each containing a set of attributes. In Chapters 1 and 11, we saw GraphQL scalar types. In Strawberry there isn’t anything special to describe these scalars, apart from strawberry.ID. As you can see in Listing 12-4, most scalar types are represented as Python primitives: str, int, and bool. The only exception to this are the types for date and due_date, which we declared as strings in the original GraphQL schema. Since types in Strawberry are dataclasses, and dataclasses are “just” Python code, instead of strings for our date, we can now use datetime.date objects. This was one of our unsolved problems in Chapter 11, and it’s now fixed.

Moving forward, notice how the relations are described by associating the dataclass attribute with the corresponding entity, like the User dataclass assigned to user in Invoice. Also note that the List type from Python typings to associate ItemLine to items. Previously, we used the Float scalar from GraphQL for the price of each ItemLine. In Python, we can use a more appropriate decimal.Decimal. Even from a simple listing like this, we can deduce that the Strawberry approach to writing GraphQL schemas as Python code brings a lot of benefits, including type safety, flexibility, and better handling of scalar types.

This is quite similar to the choices for our Invoice model in Django. With a bit of creativity, one could reuse this Strawberry enum in the Django model (or the other way around). With the enum in place, we are almost ready to test things out. Let’s add resolvers and queries in the next sections.

Working with Resolvers (Again)

We already learned that a GraphQL schema needs resolvers to return data.

To avoid clashing with the User GraphQL type here, we import our user model as UserModel. Next up, we declare resolvers to fulfill the original GraphQL queries, namely getClient and getClients. Notice how we pass an id as the argument to the second resolver to fetch a single user by ID as we did in the previous chapter. With these resolvers in place we can add a Query type and finally wire up the GraphQL endpoint in the next section.

Queries in Strawberry and Wiring Up the GraphQL Endpoint

With the fundamental types and the resolvers in place, we can create a code-first Query type for our API.

Both resolvers are wrapped with strawberry.field(). Notice that both queries will be converted to camel case in the GraphQL documentation, even though they are declared as snake case in our code. In the last line we load our schema into Strawberry, so it is picked up and served to the user. It is important to note that resolvers in Strawberry don’t have to be disconnected from the Query dataclass itself. In fact, we could have declared them as methods in the Query. We leave these two resolvers outside of the dataclass, but we will see mutations as methods of the Mutation dataclass in a moment.

Throughout the next sections, we will run Django under Uvicorn. Now we can head over to http://127.0.0.1:8000/billing/graphql/. This should open GraphiQL, a playground for exploring the GraphQL API. In the playground, we can send out queries and mutations and explore the schema and the integrated documentation, just as we did with Ariadne. Now that you have the big picture, you can complete the schema with input types and mutations.

Input Types and Mutations in Strawberry

We saw that input types in GraphQL are basically arguments for a mutation.

This code bears a bit of explanation. First off, we import our Django models again, this time by aliasing them to avoid clashes with the dataclasses. Next up, we define a Mutation and a method inside it. The method, named create_invoice(), takes InvoiceInput input type as a parameter and is decorated with @strawberry.mutation. Inside the method we convert the dataclass input type to a dictionary. This is important because the mutation parameter is a dataclass, not a dictionary. This way, we can pop out the keys we need, as we did with Ariadne. In the mutation, we also pop out state, which is later passed as state.value to InvoiceModel.objects.create(). At the time of this writing, Strawberry doesn’t convert automatically enums keys to strings, so we need to do a bit of data drilling. Finally, notice the type annotation for the return value of this mutation, Invoice. At the very end of the file we also load the mutation dataclass into the schema.

Mutation and input types complete our GraphQL schema for now. At this stage we could use the GraphiQL Playground to send an invoiceCreate mutation, but instead of trying things manually, we will implement the mutation in our React frontend. But first, let’s look at the implications of running Strawberry asynchronously with Django.

Working Asynchronously with the Django ORM

After setting everything up, you might have noticed that by sending even a simple query in GraphiQL, everything blows up.

Let’s look at what is going on here. First off, we move the ORM logic to two regular functions. In the first function, _get_all_clients(), we fetch all the clients from the database with .all(). We also force Django to evaluate the queryset by converting it to a list with list(). It’s necessary to evaluate the query in the asynchronous context, because Django querysets are lazy by default. In the second function, _get_client(), we simply get a single user from the database. Both functions are then called in two asynchronous functions, wrapped in sync_to_async(). This machinery will make ORM code work under ASGI.

This might seem like a lot of code to do something that Django provides out-of-the-box, namely SQL queries, but this is the price to pay at this moment in order to run Django asynchronously. In the future, we hope to have better async support for the ORM layer. For now, with these changes, we are ready to run Strawberry and Django side by side asynchronously. We can now move to the frontend to implement mutations with Apollo Client.

Creating Invoices with a Mutation

This form contains all the inputs for creating a new invoice. At the bottom, note the conditional rendering based on the state of mutationLoading.

If we test things in the browser, we should be able to send out the mutation and get a response from the server. This process can be seen in the browser’s console, as shown in Figure 12-1, where the Response tab is highlighted.

In Figure 12-1, we can see the data object containing a property named createInvoice, which holds the fields we requested from the mutation. We can also see __typename. This is part of GraphQL’s introspection capabilities, which make it possible to ask GraphQL “what type is this object”? An explanation of GraphQL introspection is out of the scope of this book, but the official documentation is a good starting point for learning more.