Lecture 282: Core GraphQL concepts

Today we'll dig into the key concepts of GraphQL. We'll cover schemas, queries, mutations, and subscriptions — the four pillars that GraphQL stands on. We'll also look at how these concepts let you design more flexible and developer-friendly APIs.

What are schemas and types in GraphQL?

A schema (Schema) is the set of rules that defines how a client can talk to the server. It enforces strong typing for your API. You can think of the schema as a contract between server and client: "Here's how you can interact with me!"

Example of a GraphQL schema:

type Query {
    hello: String
    user(id: ID!): User
}

type User {
    id: ID!
    name: String!
    email: String!
}

In this example:

• We have a Query type that defines what data can be requested:
  • The hello field returns a string.
  • The user field returns an object of type User, taking a required id parameter (ID!).

• The User type is defined and describes a user object:
  • The fields id, name, and email are strictly typed.

Core GraphQL types

GraphQL offers several built-in scalar types (Scalar Types):

• String — string.
• Int — integer.
• Float — floating-point number.
• Boolean — boolean value.
• ID — unique identifier (basically a string).

Example using these types:

type Product {
    id: ID!
    name: String!
    price: Float!
    inStock: Boolean
}

Here Product describes an item:

• The price field is a floating-point number (for example, 1299.99).
• The inStock field is optional (Boolean without !), so it can be null.

Advanced types

GraphQL also supports:

• Enum (enumerations): a fixed set of values.

    enum Role {
  ADMIN
  USER
  GUEST
  }
  

• Input (input object types): used to pass complex data.

    input CreateUserInput {
  name: String!
  email: String!
  password: String!
  }
  

• Union and Interface: for modeling flexible type hierarchies.

Queries: how to ask for data

Queries in GraphQL are how you fetch specific data from the server. The idea is that the client chooses exactly what it needs. It's like ordering a burger — you can ask for just the patty or the full combo with toppings.

Example query:

query {
    user(id: "123") {
        name
        email
    }
}

Server response:

{
  "data": {
    "user": {
      "name": "John Smith",
      "email": "john@example.com"
    }
  }
}

The key idea: the client asks only for the data it needs (name and email) and nothing extra.

Query arguments

The query user(id: "123") includes an id argument. Arguments let you narrow down what data you want. For example:

query {
    product(id: "456") {
        name
        price
    }
}

Server response:

{
  "data": {
    "product": {
      "name": "Guitar",
      "price": 1299.99
    }
  }
}

Arguments can be scalars, arrays, or even objects.

Mutations: how to change data

Mutations are operations that modify data on the server. They're analogous to POST/PUT/PATCH/DELETE in REST. For example, to create a new user you might use this mutation:

mutation {
    createUser(input: {
        name: "Jane Doe",
        email: "jane@example.com",
        password: "secret"
    }) {
        id
        name
    }
}

Server response:

{
  "data": {
    "createUser": {
      "id": "789",
      "name": "Jane Doe"
    }
  }
}

Here:

• The createUser key refers to the mutation that creates a new user.
• The input argument passes the data for creation.
• The response includes the created data: id and name.

How mutations differ from queries

Mutations always have side effects — they change state. For example, they might add a record to a database or update an existing one. Queries are safe and just return data.

Subscriptions: real-time updates

Subscriptions are GraphQL's mechanism for pushing real-time updates to clients when data changes. For example, in a chat app you can subscribe to new messages:

subscription {
    newMessage {
        id
        content
        sender {
            name
        }
    }
}

When someone posts a new message, the server automatically notifies all subscribers.

An example client payload might look like this:

{
  "data": {
    "newMessage": {
      "id": "1001",
      "content": "Hello!",
      "sender": {
        "name": "Ivan"
      }
    }
  }
}

Real-world use cases

Subscriptions are great for real-time scenarios:

• Chat applications.
• Order status notifications.
• Live metrics in monitoring dashboards.

How do these pieces work together?

GraphQL lets you combine queries, mutations, and subscriptions under a single API. For example, you can:

1. Fetch a list of users (queries).
2. Create new users (mutations).
3. Get automatic notifications when new users are added (subscriptions).

Why GraphQL can beat REST

Flexibility

REST ties resources to fixed URIs. For example:

• GET /users/123 — returns all user data.
• But what if the client only wants the user's name?

GraphQL solves this by letting you request exactly what you need.

Consolidation

GraphQL consolidates scattered REST endpoints into a single entry point. Instead of making three different REST calls to gather user, orders, and product data, GraphQL lets you do it in one request.

Example:

query {
    user(id: "123") {
        name
        orders {
            id
            products {
                name
            }
        }
    }
}

Now you know how the key GraphQL concepts work: schemas, queries, mutations, and subscriptions. Good news: we won't stay theoretical — in the next lectures we'll implement this stuff in practice. Get ready to code!