2. Building a schema
15m

Creating the blueprint for your graph

New to Apollo? We recommend checking out our introductory Lift-off series, which introduces many of the same concepts as this tutorial with helpful videos and interactive code challenges along the way. Completing the Lift-off series will also grant you the Apollo Graph Developer - Associate Certification, letting you easily share your newfound skills with the world!


If you are familiar with Apollo, this course covers building common useful features like authentication, pagination, and state management.

Every graph uses a schema to define the types of data it includes. For example, the for an online bookstore might include the following types:

# A book has a title and an author
type Book {
title: String
author: Author
}
# An author has a name and a list of books
type Author {
name: String
books: [Book]
}

In the steps below, we'll set up a GraphQL server that will enforce our 's structure, and then we'll define the itself.

Set up Apollo Server

A is only useful if our graph conforms to the 's structure. Enforcing a 's structure is one of the core features of Apollo Server, a production-ready, open-source library that helps you implement your graph's API.

From the start/server directory, let's install Apollo Server (along with our project's other dependencies):

cd start/server && npm install

The two packages you need to get started with Apollo Server are apollo-server and graphql, both of which are installed with the above command.

Now, in the /server directory let's navigate to src/index.js so we can create our server. Paste the code below into the file:

server/src/index.js
// We will cover using dotenv in a later lesson
require("dotenv").config();
const { ApolloServer } = require("apollo-server");
const typeDefs = require("./schema");
const server = new ApolloServer({ typeDefs });

This code imports the ApolloServer class from apollo-server, along with our (currently undefined) from src/schema.js. It then creates a new instance of ApolloServer and passes it the imported via the typeDefs property.

Task!

Now that Apollo Server is prepared to receive our , let's define it.

Define your schema's types

Your GraphQL defines what types of data a client can read and write to your graph. s are strongly typed, which unlocks powerful developer tooling.

Your 's structure should support the actions that your clients will take. Our example app needs to be able to:

  • Fetch a list of all upcoming rocket launches
  • Fetch a specific launch by its ID
  • Log in the user
  • Book a launch for a logged-in user
  • Cancel a previously booked launch for a logged-in user

Let's design our to make these actions straightforward.

In server/src/schema.js, import gql from apollo-server and create a called typeDefs for your :

server/src/schema.js
const { gql } = require("apollo-server");
const typeDefs = gql`
# Your schema will go here
`;
module.exports = typeDefs;

The will go inside the gql function (between the backticks). The language we'll use to write the is GraphQL's ().

Because the sits directly between your application clients and your underlying data services, frontend and backend teams should collaborate on its structure. When you develop your own graph, practice schema-first development and agree on a before you begin implementing your API. Apollo GraphOS is highly recommended for teams who need to collaborate on GraphQL design and implementation.

Object types

Most of the definitions in a GraphQL are object types. Each you define should represent an object that an application client might need to interact with.

For example, our example app needs to be able to fetch a list of upcoming rocket launches, so we should define a Launch type to support that behavior.

Paste the following inside the backticks of the typeDefs declaration in server/src/schema.js:

server/src/schema.js
type Launch {
id: ID!
site: String
mission: Mission
rocket: Rocket
isBooked: Boolean!
}

The Launch has a collection of fields, and each has a type of its own. A 's type can be either an or a scalar type. A type is a primitive (like ID, String, Boolean, Int or Float) that resolves to a single value. In addition to GraphQL's built-in types, you can define custom scalar types.

An exclamation point (!) after a declared 's type means "this 's value can never be null."

In the Launch definition above, Mission and Rocket refer to other s. Let's add definitions for those, along with the User type (again, all inside the backticks):

server/src/schema.js
type Rocket {
id: ID!
name: String
type: String
}
type User {
id: ID!
email: String!
trips: [Launch]!
token: String
}
type Mission {
name: String
missionPatch(size: PatchSize): String
}
enum PatchSize {
SMALL
LARGE
}

If a declared 's type is in [Square Brackets], it's an array of the specified type. If an array has an exclamation point after it, the array cannot be null, but it can be empty.

Notice above that the missionPatch of the Mission type takes an argument named size, which is of the enum type PatchSize. When you query for a that takes an , the 's value can vary depending on the provided 's value. In this case, the value you provide for size will determine which size of the mission's associated patch is returned (the SMALL size or the LARGE size).

The Query type

We've defined the objects that exist in our graph, but clients don't yet have a way to fetch those objects. To resolve that, our needs to define queries that clients can execute against the graph.

You define your graph's supported queries as s of a special type called the Query type. Paste the following into your definition:

server/src/schema.js
type Query {
launches: [Launch]!
launch(id: ID!): Launch
me: User
}
Task!

This Query type defines three available queries for clients to execute: launches, launch, and me.

  • The launches query will return an array of all upcoming Launches.
  • The launch query will return a single Launch that corresponds to the id argument provided to the query.
  • The me query will return details for the User that's currently logged in.

The Mutation type

Queries enable clients to fetch data, but not to modify data. To enable clients to modify data, our needs to define some mutations.

The Mutation type is a special type that's similar in structure to the Query type. Paste the following into your definition:

server/src/schema.js
type Mutation {
bookTrips(launchIds: [ID]!): TripUpdateResponse!
cancelTrip(launchId: ID!): TripUpdateResponse!
login(email: String): User
}

This Mutation type defines three available s for clients to execute: bookTrips, cancelTrip, and login.

  • The bookTrips mutation enables a logged-in user to book a trip on one or more Launches (specified by an array of launch IDs).
  • The cancelTrip mutation enables a logged-in user to cancel a trip that they previously booked.
  • The login mutation enables a user to log in by providing their email address.

The bookTrips and cancelTrip s return the same : a TripUpdateResponse. A 's return type is entirely up to you, but we recommend defining special s specifically for responses.

Add the definition for TripUpdateResponse to your :

server/src/schema.js
type TripUpdateResponse {
success: Boolean!
message: String
launches: [Launch]
}

This response type contains a success status, a corresponding message, and an array of any Launches that were modified by the . It's good practice for a to return whatever objects it modifies so the requesting client can update its cache and UI without needing to make a follow-up query.

Task!

Our example app's is now complete!

Run your server

Return to server/src/index.js and add the following call to the bottom of the file:

server/src/index.js
server.listen().then(() => {
console.log(`
Server is running!
Listening on port 4000
Explore at https://studio.apollographql.com/sandbox
`);
});

After saving, run npm start to start your server! 🎉 Apollo Server is now available at http://localhost:4000.

Task!

Explore your schema

Now that our server is running, we can introspect its types and s with useful developer tools. Later, we'll also be able to run test queries from those tools.

is a helpful GraphQL feature that enables you to obtain a server's for development purposes. It should be disabled for servers running in production. Apollo Server disables automatically if the NODE_ENV environment is set to production.

The Apollo Studio Explorer is a powerful web IDE for exploring your GraphQL and building queries against it:

Studio Explorer tab

Apollo Sandbox is a special mode of Apollo Studio that enables you to use Studio features without an Apollo account. Let's try it out!

Visit studio.apollographql.com/sandbox. When Sandbox opens, it automatically attempts to connect to your server running at http://localhost:4000.

To introspect your server's in Sandbox, click the Documentation tab on the left side:

Explorer documentation tab

Your 's root types (Query and Mutation) appear. You can click any type to view its s and step down into your . You'll see that the types and s match what we provided to our server.

Our server now knows which GraphQL types and s it supports, but it doesn't know where to obtain the data to respond to those s. Next, we'll connect our server to two s.

Previous
Next