GraphQL

GraphQL is a typed query language for APIs: clients ask for exact fields from one endpoint. Learn how it works, N+1 and caching trade-offs, and testing.

What is GraphQL?

GraphQL is a query language for APIs and a runtime that fulfils those queries. A server publishes a strongly typed schema, and the client sends a query naming exactly the fields it wants. The response mirrors the shape of the query. Unlike a typical REST API, a GraphQL service is usually served from a single URL, often /graphql. The language is defined in the GraphQL specification.

How GraphQL works

Schema and operations

The schema describes the types and fields a client can ask for. There are three operation types: a query reads data, a mutation changes data and triggers side effects, and a subscription delivers real-time updates. Queries can use arguments, variables, aliases and fragments, and validation rejects a query that does not match the schema before it runs. Resolvers then produce the data for each field.

One request, one response shape

A query for a user's name and email returns only those two fields under a top-level data key. If something goes wrong, the response carries an errors key. A request is normally an HTTP POST with a JSON body holding query, operationName and variables. A server may also accept GET, but only for queries, never for mutations. See serving GraphQL over HTTP for the details.

Introspection

Introspection lets a client query the schema itself, through fields such as __schema and __type. It powers documentation browsers and editor auto-complete. The GraphQL docs note that APIs used only by your own apps often do not need it in production, and that disabling it is common because it reduces the attack surface.

Example

A mobile screen needs a product name and its three latest reviews. With REST that can mean one call for the product and another for the reviews. With GraphQL the client sends one query asking for product(id: "42") { name reviews(first: 3) { text } } and gets exactly that back. The trade-off moves to the server, which must resolve every nested field efficiently.

Common mistakes and trade-offs

  • The N+1 problem. Resolving a list of items and then fetching related data for each one triggers one extra backend call per item. Batching, for example with DataLoader, collects those lookups into a single request.
  • Unbounded queries. Because the client shapes the query, a deeply nested or very broad one can load the server heavily. Paginate list fields (API pagination) and use depth, breadth and complexity limits, plus timeouts.
  • Weaker HTTP caching. REST gives every resource a URL that HTTP caches understand. GraphQL has no such built-in identity, so the API should expose a globally unique id that clients can use to build a cache. See API caching.
  • Assuming HTTP 200 means success. A response with data can still contain errors, and HTTP has no status for partial success. Check the body, not only the status code.
  • Security left to the schema alone. Authentication, authorization and operation limits still apply. Read API security.

GraphQL, load testing and API monitoring

Every GraphQL operation is an HTTP request to one endpoint, so a slow resolver or an N+1 pattern shows up as response time under load, not as a failing URL. Use load testing with realistic queries, since a cheap query and an expensive one share the same URL. For ongoing checks, the API monitoring FAQ states that GraphQL is supported as a POST with a JSON body. Add an assertion on the response body so a 200 that contains errors still fails the check, and see what API monitoring is. Related reading: 10 common API performance issues and how to detect them and how API monitoring helps your business.

FAQ

Is GraphQL a database?

No. GraphQL is a query language and runtime for APIs. It sits in front of your existing data sources, such as databases, services and other APIs, and the resolvers decide where each field comes from.

What is the difference between GraphQL and REST?

REST exposes many URLs, each returning a fixed resource shape. GraphQL usually exposes one endpoint where the client chooses the fields it wants. GraphQL reduces over-fetching but moves more work and caching complexity to the server side.

Does GraphQL use POST for everything?

Queries and mutations are normally sent as POST requests with a JSON body. The GraphQL over HTTP guidance allows GET for queries only, and mutations must use POST.

Should I disable introspection in production?

For APIs used only by your own applications it is typically not needed in production, and disabling it is common. It is one part of a wider approach that also includes authentication, authorization, depth limits and cost analysis.

Can I monitor a GraphQL API with LoadFocus?

The LoadFocus API monitoring page states that GraphQL is supported as a POST with a JSON body. Add a body assertion so errors returned with a 200 status are caught.

How fast is your website?

Elevate its speed and SEO seamlessly with our Free Speed Test.

Free Website Speed Test

Analyze your website's load speed and improve its performance with our free page speed checker.