GraphQL is a query language for APIs and a runtime for executing those queries against a type system that you define for your data.

Unlike a traditional REST API, where the server exposes multiple endpoints such as /users, /users/42, and /users/42/posts, GraphQL generally exposes a single endpoint through which the client describes the data it needs.

The important idea is that the client does not simply ask the server for a resource. It asks for a specific shape of data.

For example, a client might request:

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

The response follows the structure requested by the client:

{
  "data": {
    "user": {
      "id": "42",
      "name": "Suriya",
      "email": "suriya@example.com"
    }
  }
}

GraphQL itself does not require MongoDB, Node.js, React, Apollo, or any particular programming language. It defines a specification for describing an API schema, querying that schema, validating operations, and executing them.

A GraphQL server typically has three important responsibilities:

1. Define the schema that describes available data and operations.
2. Validate incoming operations against that schema.
3. Execute valid operations using resolver functions.

This separation between the API contract and the underlying data sources is one of GraphQL's most important architectural characteristics.

GraphQL was designed to solve problems that became increasingly visible as client applications became more sophisticated.

A traditional REST API often models server resources through endpoints. That model works well for many applications, but complex user interfaces can require data from many related resources.

Imagine a social application displaying a user's profile, recent posts, author information, comments, and reactions. A REST client might need several requests:

GET /users/42
GET /users/42/posts
GET /posts/101/comments
GET /posts/101/reactions

This can create several problems.

Over-fetching

An endpoint may return fields that the client does not need. A mobile application might only require a user's name and avatar, while /users/42 returns dozens of additional fields.

Under-fetching

A response may not contain enough information to render the screen, forcing the client to make additional requests.

Endpoint proliferation

As application requirements grow, teams may add increasingly specialized endpoints for different clients and screens.

Client-specific requirements

A web application, mobile application, admin application, and smart TV application may need different representations of the same underlying data.

GraphQL addresses these issues by allowing clients to select the fields they need from a typed graph of related data.

However, GraphQL is not automatically better than REST in every situation. REST remains an excellent choice for many APIs. The correct choice depends on requirements such as caching strategy, operational complexity, team experience, API consumers, and data access patterns.

GraphQL and REST can both be used to build production APIs, but they model API interaction differently.

In REST, the API is usually organized around resources and HTTP endpoints. In GraphQL, the API is organized around a typed schema and operations.

A REST API might expose:

GET    /users/42
GET    /users/42/posts
POST   /users
PATCH  /users/42
DELETE /users/42

A GraphQL API may expose a single endpoint such as /graphql, with operations represented in the schema:

query {
  user(id: "42") {
    name
    posts {
      title
    }
  }
}

GraphQL's single endpoint does not mean that GraphQL has only one operation. The schema can expose many query fields and mutation fields through that endpoint.

REST strengths

REST integrates naturally with HTTP semantics. HTTP caching, status codes, proxies, CDNs, and resource-oriented tooling are well understood.

GraphQL strengths

GraphQL provides a strongly typed schema, client-controlled selection sets, nested data fetching, introspection, and a unified API contract.

Important distinction

GraphQL does not eliminate HTTP. GraphQL is frequently transported over HTTP. It changes how API operations and response shapes are modeled rather than replacing the network itself.

Before writing a serious GraphQL application, you need to understand the vocabulary used by the specification and ecosystem.

Schema

The schema defines what clients are allowed to query and what data types and operations are available.

Type

A type describes the shape of data. Examples include User, Product, Order, and Post.

Field

A field is a property or operation exposed by a type.

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

Here id, name, and email are fields.

Query

A query is a read operation. It retrieves data without being intended to modify server state.

Mutation

A mutation represents an operation that changes server-side state, such as creating, updating, or deleting data.

Subscription

A subscription represents a long-lived operation used for receiving events or updates, commonly through a real-time transport.

Resolver

A resolver is a function responsible for obtaining or computing the value of a field.

Selection set

The fields enclosed inside { } after an object field form a selection set.

user {
  id
  name
}

Argument

An argument supplies input to a field.

user(id: "42")

Scalar

A scalar represents a leaf value such as String, Int, Float, Boolean, or ID.

These concepts build on each other. A schema defines types, types contain fields, fields can accept arguments, clients select fields in operations, and resolvers provide the values during execution.

A GraphQL request goes through several conceptual stages before the client receives a response.

Suppose the client sends:

query GetProduct($id: ID!) {
  product(id: $id) {
    id
    name
    price
  }
}

with variables:

{
  "id": "p100"
}

The server conceptually performs the following steps.

1. Receive the operation

The server receives the GraphQL document and any variables.

2. Parse

The GraphQL document is converted into an internal representation called an AST, or Abstract Syntax Tree.

3. Validate

The operation is checked against the schema. The server verifies that fields exist, arguments have valid types, required values are present, and selections are valid.

4. Execute

If validation succeeds, GraphQL executes the operation. Resolver functions are invoked to obtain the requested values.

5. Complete values

GraphQL processes returned values according to the field types. This includes handling nested objects, lists, scalar serialization, and nullability rules.

6. Return the response

The result normally contains a data property and may also contain an errors property.

For example:

{
  "data": {
    "product": {
      "id": "p100",
      "name": "Keyboard",
      "price": 2499
    }
  }
}

Understanding this lifecycle becomes extremely important later when debugging validation errors, resolver failures, null propagation, authorization behavior, and performance issues.