The Schema: Types, Queries and Mutations

Schema first

Every GraphQL API is defined by a strongly-typed schema that describes what data exists and what operations are allowed. The schema is the contract between client and server.

Object types

type User {
  id: ID!
  name: String!
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

Fields have types. A trailing ! means non-null (required); [Post!]! is a non-null list of non-null Posts. Scalar types are Int, Float, String, Boolean and ID.

Query: reading data

The special Query type lists the read entry points clients can start from:

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

Mutation: writing data

The Mutation type lists operations that change data. Inputs are typically grouped into an input type:

input NewPost { title: String!, authorId: ID! }

type Mutation {
  createPost(data: NewPost!): Post!
  deletePost(id: ID!): Boolean!
}

A client calls a mutation and, in the same request, selects which fields of the result it wants back.

Key points

• A typed schema defines all data and operations – it is the API contract.
• Object types have fields; ! marks non-null, [T] marks a list.
• The Query type declares read entry points.
• The Mutation type declares operations that change data.