What is GraphQL?

The client describes the response

In a typical REST API every resource has its own URL and the server decides what each response contains. GraphQL flips that. The server publishes a typed schema of everything it can provide, and the client writes a query naming the fields it wants. Queries usually go to one endpoint, conventionally /graphql, and the JSON response mirrors the shape of the query.

query {
  customer(id: "42") {
    name
    recentOrders(first: 3) {
      number
      total
    }
  }
}

{
  "data": {
    "customer": {
      "name": "Jane Doe",
      "recentOrders": [
        { "number": "S-1042", "total": 1499.9 },
        { "number": "S-1017", "total": 320 },
        { "number": "S-0988", "total": 75.5 }
      ]
    }
  }
}

Over-fetching and under-fetching

Over-fetching means getting more than you need: the mobile app's customer card needs a name, but /customers/42 returns forty fields. Under-fetching means one request is not enough: after fetching the customer you need a second call for recent orders and a third for each order's shipping status. On a slow mobile connection those sequential round trips add up quickly. With GraphQL the same screen is served by one query that returns only the fields it renders.

Schema, resolvers and operation types

The schema defines the types, their fields, which fields are non-nullable and which take arguments. Behind every field sits a resolver, a function that knows where the value comes from: a database query, another REST service, a cache. That is why GraphQL is not a database language; it is an interface layer that is indifferent to where data lives. There are three operation types: query for reads, mutation for writes and subscription for real-time updates. Through introspection, clients can ask the schema to describe itself, which is what powers autocomplete in GraphQL tooling.

GraphQL over HTTP

The common transport is a POST with an application/json body containing a required query plus optional variables and operationName. Read-only queries may also be sent with GET; mutations may not. Responses carry data and, when something failed, an errors array. Unlike REST, partial success is normal: some fields resolve while others fail, and the HTTP status can still be 2xx. The official serving over HTTP guide covers status codes and media types in detail.

The price of flexibility

• Caching: with everything sent as a POST to one URL, browser and CDN caching no longer comes for free. Client-side normalized caches or persisted queries fill the gap.
• The N+1 problem: naive resolvers fire one database query per list item; a batching layer such as DataLoader is standard practice.
• Abuse resistance: since clients compose queries freely, servers need depth and complexity limits, cost-based rate limiting and field-level authorization.

GraphQL shines when many clients need differently shaped data from the same backend. For a service with a handful of well-defined resources and public, cacheable responses, plain REST is often the simpler choice.