Building a schema

6. Building a schema

Overview

Time to level up from "Hello world" to "Hello playlists"!

In this lesson, we will:

Examine a mockup design and create a GraphQL schema from it
Create our first object type
Learn how to document a GraphQL schema with the description argument

The mockup

To kick things off, let's take a look at this page from the MusicMatcher app:

A grid of featured playlists

It showcases a grid of featured popular playlists that you may be interested in!

Breaking each playlist down, we can start to see what pieces of data the client app will need. This process of breaking down a mockup to pieces of data is called schema-first design.

Schema-first design means we'll implement the feature based on exactly which data our client application needs. Schema-first design typically involves three major steps:

Defining the schema: We identify which data our feature requires, and then we structure our schema to provide that data as intuitively as possible.
Backend implementation: We build out our GraphQL API and fetch the required data from whichever data sources contain it.
Frontend implementation: Our client consumes data from our GraphQL API to render its views.

One of the benefits of schema-first design is that it reduces total development time by allowing frontend and backend teams to work in parallel. The frontend team can start working with mocked data as soon as the schema is defined, while the backend team develops the API based on that same schema. This isn't the only way to design a GraphQL API, but we believe it's an efficient one, so we'll use it throughout this course.

The same mockup but with labels for each piece of data

A playlist needs a name and a description, which are both pieces of text.

Strawberry uses a code-first approach to implementing a GraphQL server but it's still helpful to keep the schema-first design principles in mind; thinking about what types and fields our resolver functions will be defining based on the mockup designs and data that the app developers expect.

The `Playlist` type

Let's start with the Playlist type. In the types folder, create a file called playlist.py.

📦 odyssey-intro-strawberry
┣ 📂 api
┃ ┣ 📂 types
┃ ┃ ┣ 📄 __init__.py
┃ ┃ ┗ 📄 playlist.py
┃ ┣ 📄 __init__.py
┃ ┣ 📄 query.py
┃ ┗ 📄 schema.py
┣ 📄 // other folders & files

We'll import strawberry at the top, define the class and apply the @strawberry.type annotation to it.

api/types/playlist.py

import strawberry

@strawberry.type
class Playlist:
    ...
    # Playlist properties go here

Inside the Playlist class, we'll start by defining the name of our playlist as a property with type str.

api/types/playlist.py

name: str

By default, this field is non-nullable, so a playlist requires a name.

Next, let's define the playlist's description, which is also a str type. A description can be null, so we'll mark it as such using the | None syntax.

api/types/playlist.py

description: str | None

If you're using a version of Python older than 3.10, you can use the Optional type from the typing module to define a nullable field. For example, description: Optional[str].

api/types/playlist.py

from typing import Optional

import strawberry

@strawberry.type
class Playlist:
    name: str
    description: Optional[str]

One more thing! Even though it wasn't part of the mockup, it's common practice to also define an identifier for a class. Looking ahead, when we click into a playlist, we'll need to have a way to retrieve the details for that specific playlist, and that's exactly what the identifier (or ID) is for.

IDs in GraphQL are represented as ID scalar types. Python doesn't have a built-in ID type, but fortunately, Strawberry provides a strawberry.ID type that we can use.

api/types/playlist.py

id: strawberry.ID

The three properties we've defined for a playlist (id, name and description) act as the resolvers for those fields. Behind the scenes, Strawberry automatically generates resolvers for each field based on the property name. For example, the name field will have a resolver that returns the value of the name property.

import strawberry

@strawberry.type
class Playlist:
    id: strawberry.ID
    name: str
    description: str | None

Exploring the schema

What does this Playlist class look like in our GraphQL schema now? Let's find out!

We'll first need to register the Playlist class with our GraphQL schema.

Open up the api/schema.py file and import the Playlist class at the top of the file.

api/schema.py

from .types.playlist import Playlist

Next, where we defined strawberry.Schema, we'll add another parameter called types and assign the Playlist class in the list it accepts.

api/schema.py

schema = strawberry.Schema(query=Query, types=[Playlist])

Save all our changes and restart the server.

Back to Sandbox, let's check out the Schema page. Select Objects on the left-hand side and click Playlist.

http://localhost:8000

Sandbox showing Schema Reference and Objects selected

Awesome, we've accounted for all the playlist fields!

http://localhost:8000

Sandbox showing Playlist schema

Right now, the details column shows "No description". Although the field names feel fairly self-explanatory right now, it's good practice to document the types and fields of your schema, especially for consumers of our graph.

Documenting our schema

We use GraphQL descriptions to document a schema. (Not to be confused with our playlist's description field!) In Strawberry we use the description argument of strawberry.type, which takes a string as an argument that describes the type.

Back to our Playlist class, let's add the description argument to the @strawberry.type decorator.

api/types/playlist.py

@strawberry.type(
    description="A curated collection of tracks designed for a specific activity or mood."
)
class Playlist:
    ...

Next, let's add GraphQL descriptions to the Playlist fields. We'll need to use the strawberry.field function for each field, passing in the description argument.

api/types/playlist.py

id: strawberry.ID = strawberry.field(description="The ID for the playlist.")
name: str = strawberry.field(description="The name of the playlist.")
description: str | None = strawberry.field(
    description="Describes the playlist, what to expect and entices the user to listen."
)

import strawberry

@strawberry.type(
    description="A curated collection of tracks designed for a specific activity or mood."
)
class Playlist:
    id: strawberry.ID = strawberry.field(description="The ID for the playlist.")
    name: str = strawberry.field(description="The name of the playlist.")
    description: str | None = strawberry.field(
        description="Describes the playlist, what to expect and entices the user to listen."
    )

Save our changes and switch over to Sandbox to see our clear and helpful descriptions!

http://localhost:8000

Sandbox showing Playlist schema with descriptions

Practice

Which of the following statements are true about schema documentation?

It improves the performance of GraphQL queriesIt helps consumers understand the purpose and structure of the GraphQL schemaIt is optionalIt is required for GraphQL schema validation

In Apollo Sandbox, what page would you navigate to for a detailed reference to your GraphQL schema?

ChecksExplorerSchema - SDLOperations

Key takeaways

Breaking down a mockup into data pieces and implementing features based on client application needs is known as schema-first design.
The description argument on both strawberry.field and strawberry.type is used to add clear and helpful descriptions to GraphQL types and fields. It will be displayed in GraphQL IDEs such as Apollo Sandbox.
The strawberry.ID type defines the identifier for the GraphQL type. It indicates that the associated property represents a unique identifier.

Up next

We need a way to query for a playlist. Right now, it's just floating in our schema without a way to access it. Let's make it available through our Query type — our entry point to the schema!

Share your questions and comments about this lesson

This course is currently in

beta

. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.

Overview

The mockup

The Playlist type

Exploring the schema

Documenting our schema

Practice

Key takeaways

Up next

Share your questions and comments about this lesson

The `Playlist` type