Cheatsheet - GraphQL

Core Concepts

• Schema: The heart of a GraphQL API, the schema defines the types of data that clients can query. It acts as a contract between the client and the server.
• Types: The schema is built from types. The most common are:
  • Object Types: Custom data structures you define. For example, type User { id: ID!, name: String }.
  • Scalar Types: Basic data types like Int, Float, String, Boolean, and ID.
• Fields: Units of data you can request on a type. They become the fields in the JSON response.
• Queries: Used to fetch data. They are read-only operations.
• Mutations: Used to modify data (create, update, delete). They are write-followed-by-a-read operations.
• Subscriptions: A way to maintain a real-time connection to the server, enabling you to get instant updates for specific events.
• Resolvers: Server-side functions that are responsible for fetching the data for a single field in your schema.

Schema Definition Language (SDL)

GraphQL has its own language to define the schema. Here's a quick look at the syntax:

Defining an Object Type:

type Book {
  title: String!
  author: Author
}

type Author {
  name: String!
  books: [Book]
}

• The ! indicates a non-nullable field.
• [Book] represents a list of Book objects.

Root Types: There are three special root types: Query, Mutation, and Subscription. These define the entry points for your API.

type Query {
  getbook(id: ID!): Book
  getbooks: [Book]
}

type Mutation {
  addBook(title: String!, author: String!): Book
}

Queries

Basic Query: Ask for specific fields on an object.

{
  book(id: "1") {
    title
    author {
      name
    }
  }
}

Arguments: Pass arguments to fields to specify which data to fetch.

{
  books(limit: 5) {
    title
  }
}

Aliases: Rename fields in your results to avoid naming conflicts.

{
  book1: book(id: "1") {
    title
  }
  book2: book(id: "2") {
    title
  }
}

Fragments: Reusable units of fields for complex queries.

{
  book(id: "1") {
    ...bookFields
  }
}

fragment bookFields on Book {
  title
  author {
    name
  }
}

Variables: To make queries dynamic, you can use variables. This helps avoid string manipulation on the client-side.

query GetBook($bookID: ID!) {
  book(id: $bookID) {
    title
  }
}

// Separate JSON variables:
{
  "bookID": "1"
}

Mutations

Mutations modify data on the server. The syntax is similar to queries but must use the mutation keyword.

mutation CreateBook($title: String!, $author: String!) {
  addBook(title: $title, author: $author) {
    title
    author {
      name
    }
  }
}

// Separate JSON variables:
{
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald"
}

Advanced Concepts

• Introspection: GraphQL allows you to query the schema itself. This is a powerful feature for tools and documentation.
• Interfaces: An abstract type that includes a certain set of fields that a type must include to implement the interface.
• Unions: Similar to interfaces, but they don't specify any common fields between the types.
• Directives: Annotations that can be attached to a field or fragment to affect how it's executed. The built-in directives are @include(if: Boolean) and @skip(if: Boolean).

Common Scalar Types

Type	Description
Int	A signed 32-bit integer.
Float	A signed double-precision floating-point value.
String	A UTF-8 character sequence.
Boolean	true or false.
ID	A unique identifier, serialized as a String.