GraphQL.

GraphQL lets each client fetch exactly the data it needs in one request, from a typed schema that describes the API.

• No over-fetching. The client names the fields it wants and gets only those.
• No under-fetching. Related data, like a user and their posts, comes in one request instead of several round trips.
• A typed contract. The schema defines every type and field, and the server rejects queries for fields that do not exist.
• Self-documenting. Introspection lets tools read the schema, which powers editor tooling, documentation and debugging.
• Web and mobile clients can ask the same endpoint for different fields.
• The API evolves without versions. New fields do not break old queries, and old fields are deprecated instead of removed.

GraphQL has three operation types: query for reading, mutation for writing, and subscription for real-time updates. Each starts at its own root type in the schema, Query, Mutation or Subscription, whose fields are that operation's entry points.

1. A query reads data. The server can resolve its fields in parallel.
2. A mutation writes data. Its top-level fields run one after another, so two writes in one request never race.
3. A subscription keeps a long-lived request open, and the server pushes new data each time an event happens.

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

mutation CreateUser {
  createUser(input: { name: "John" }) {
    name
  }
}

subscription UserUpdates {
  userUpdated(id: "123") {
    name
  }
}

A GraphQL schema is the contract between client and server. It defines every type and its fields, how the types relate, and which operations a client can run.

The server checks each request against the schema before running it, so a query for a missing field fails early. That makes the schema the single source of truth for what data can be fetched and how.

Schemas are usually written in the Schema Definition Language (SDL). Here Query lists the entry points for reading, and User.posts links each user to their posts.

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

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

Scalars are the primitive data types in GraphQL, and they represent leaf values. A scalar field has no sub-fields to select, so the query stops there. Scalars also type arguments and variables.

The five built-in scalars are:

• String: a UTF-8 character sequence.
• Int: a 32-bit signed integer.
• Float: a double-precision floating-point number.
• Boolean: true or false.
• ID: a unique identifier. It is serialized like a String and often used as a cache key.

You can also define custom scalars such as Date or Email, and the server supplies the code that serializes, parses and validates them. @specifiedBy can link one to its format specification.

scalar Date
scalar Email
scalar URL

type User {
  id: ID!
  email: Email!
  birthDate: Date
}

Every field in GraphQL is nullable by default, so it may return null. An exclamation mark after the type, as in String!, makes the field non-nullable, which promises it will never be null.

The default exists because many things can fail in a networked service. A database can go down or a permission check can fail. A nullable field lets that one field come back as null while the rest of the response still arrives.

A non-nullable field trades that safety for a stronger promise. If its resolver fails or returns null, the null propagates to the nearest nullable parent field, which becomes null instead.

Lists combine both markers. [Post!]! means neither the list nor its items can be null, while [String] allows both to be null.

type User {
  id: ID!           # Required field
  name: String!     # Required field
  email: String     # Optional field (can be null)
  age: Int          # Optional field
  posts: [Post!]!   # Required array of required Posts
  tags: [String]    # Optional array of optional strings
}

An object type describes one kind of entity in your domain, like a user or a post. It lists the named fields a client can ask for. Object types are the most common type in a GraphQL schema.

You define one in the Schema Definition Language (SDL) with the type keyword, a name and typed fields. A field can return a scalar like String! or another object type like User!. That is how types link: User.posts returns posts, and Post.author returns a user.

The root Query type is an object type too. Its fields are the entry points for reading data.

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

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

An enum is a type whose value must be one of a fixed list of names, such as ADMIN or GUEST. It adds type safety and validation in both directions.

For input, the server rejects an argument outside the list before any resolver runs. For output, clients know the field holds only those values. They can handle each case, and code generators can produce matching types.

Use an enum for a small set of values known ahead of time, like roles, statuses or sort orders. If the values change often or come from data, use a String or an object type instead.

enum UserRole {
  ADMIN
  MODERATOR
  USER
  GUEST
}

type User {
  id: ID!
  name: String!
  role: UserRole!
}

An input type is an object you pass in as an argument, while a regular object type is what the server returns. You declare an input type with the input keyword instead of type.

The two cannot be mixed. An input type's fields can only be scalars, enums or other input types, and lists of those. Input fields also cannot take arguments. An object type's fields, by contrast, can return other object types and can each have a resolver.

Input types are used for arguments in mutations and queries. They group many values into one structured argument. A common pattern is one input per mutation. CreateUserInput has required fields, while UpdateUserInput has optional ones, so a client sends only the fields it changes.

input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

input UpdateUserInput {
  name: String
  email: String
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

GraphQL is a query language for APIs, and a runtime that executes those queries against a typed schema. The client describes the data it wants, and gets exactly that shape back.

The main differences:

• REST exposes many URLs, one per resource. GraphQL usually exposes one endpoint.
• A REST endpoint returns a fixed shape, so clients over-fetch unused fields or under-fetch and make extra calls. A GraphQL query gets related data in one request.
• A GraphQL schema is typed, and tools can read it through introspection, a query that returns the schema. REST APIs describe themselves with separate documentation.
• REST APIs often add versions such as /v2. GraphQL APIs usually add fields and deprecate old ones.

REST is easier to cache over HTTP, because each URL is a natural cache key.