Odyssey

Intro to GraphQL with TypeScript & Apollo Server

Course overview and setupGraphQL basicsSchema definition language (SDL)Building the schemaApollo ServerApollo Sandbox ExplorerThe listings REST APIResolversCodegenQuerying real dataQuery argumentsAdding the Amenity typeResolver chainsMutations
4. Building the schema
2m

Overview

Time to put what we learned about SDL to work.

In this lesson, we will:

  • Define our schema

Building the schema

Let's navigate to the src directory. In there, we're going to create a new file called schema.graphql.

đź“‚ src
┣ 📄 graphql.d.ts
┣ 📄 helpers.ts
┣ 📄 index.ts
â”— đź“„ schema.graphql

✏️ Let's define that schema

Referring back to our featured listings mockup, we identified that we need some data for each listing.

A screenshot of Airlock, focused on the row of featured listings and their required fields

For this course, we're going to skip the listing photo and overall rating, and tackle a slightly pared-down version of the mockup.

Here are the basic fields we'll start with:

  • title
  • numOfBeds
  • costPerNight
  • closedForBookings

We'll also need a field that we can use to differentiate one listing from another—we'll give this field the name id.

With our set of fields in mind, let's bring the Listing type to life!

The Listing type

Let's define the Listing type in our schema.graphql file and add a description right away.

schema.graphql
"A particular intergalactic location available for booking"
type Listing {
# Fields go here
}

Now for the listing's fields, we'll have:

  • id of type ID!
  • title of type String!
  • numOfBeds of type Int
  • costPerNight of type Float
  • closedForBookings of type Boolean

So we should end up with a Listing type that looks like this:

Be sure to note the nullability of each of your Listing type's fields!

schema.graphql
"A particular intergalactic location available for booking"
type Listing {
id: ID!
"The listing's title"
title: String!
"The number of beds available"
numOfBeds: Int
"The cost per night"
costPerNight: Float
"Indicates whether listing is closed for bookings (on hiatus)"
closedForBookings: Boolean
}

Not seeing the nice GraphQL syntax highlighting you want? Check out the GraphQL: Syntax Highlighting extension for VS Code.

The Listing type is complete for now, but we need a way to actually ask our GraphQL server for listing data. For that, we have a separate Query type.

The Query type

The Query type is defined like any other object type:

schema.graphql
type Query {
# Fields go here
}

The fields of this type are entry points into the rest of our schema. These are the top-level fields that our client can query for. For now, we're only interested in fetching the list of featured listings for our homepage.

Let's name the field featuredListings to make it as descriptive as possible. We want this field to return a non-nullable list of non-nullable Listing types ([Listing!]!). Fields on the Query type can return null, but in this case, we know our data source will return data for the listings. Don't forget to add a description for the field!

schema.graphql
type Query {
"A curated array of listings to feature on the homepage"
featuredListings: [Listing!]!
}

Our schema is now fully defined to support our first feature!

Not to worry—those exclamation points can be tricky. A good tip is to start from the outside and move your way in.

The outermost exclamation point (!) applies to the array ([]) itself. This means that the array can be empty—it just CAN'T be null. The featured listings list might contain zero listings, so this syntax states that at the very least we should return an empty array, or list, to stand in for featuredListings.

Next, inside of the square brackets ([]), we'll see another exclamation point (!) applied to the Listing type. This bit of syntax specifies that the list returned should either contain objects that adhere to the Listing GraphQL type structure, or it should be empty. In other words, an array like [1,2,3] or [null, null] is not allowed!

type Query {
"A curated array of listings to feature on the homepage"
featuredListings: [Listing!]!
}
"A particular intergalactic location available for booking"
type Listing {
id: ID!
"The listing's title"
title: String!
"The number of beds available"
numOfBeds: Int
"The cost per night"
costPerNight: Float
"Indicates whether listing is closed for bookings (on hiatus)"
closedForBookings: Boolean
}

Practice

Which of these statements about the Query type are true?
Code Challenge!

Define a Query type with a field, popularPlanets, that returns a non-null List of non-null Planet types. Remember to give your field a description!

Key takeaways

  • We use the Query type to define the top-level fields a client can query for. These fields are the entry points into our schema.

Up next

This course is all about building a GraphQL server, so let's get into it! It's time to meet Apollo Server.

Previous
Next

Share your questions and comments about this lesson

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.

              SDL

              GraphQL's schema definition language (SDL). The syntax for writing GraphQL schemas. All GraphQL APIs can use SDL to represent their schema, regardless of the API's programming language.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              object type

              A type in a GraphQL schema that has one or more fields. User is an object type in the following example:

              type User {
              name: String!
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              Fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
              # id, firstName, and lastName are all fields of the Author type
              id: Int!
              firstName: String
              lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              Apollo Server

              An open-source library for server-side GraphQL operation handling. It can be used as a monolithic GraphQL server or a subgraph server within a supergraph.

              NEW COURSE ALERT

              Introducing Apollo Connectors

              Connectors are the new and easy way to get started with GraphQL, using existing REST APIs.

              Say goodbye to GraphQL servers and resolvers—now, everything happens in the schema!

              Take the course