{"canonical_url":"https://engineer.company/glossary/graphql/","content_markdown":"# GraphQL\n\n## What it is\n\nGraphQL is a query language for APIs together with the runtime that carries out\nthose queries on the server. The client sends a document that names exactly the\nfields it wants, and the server answers with data shaped the same way. The\nspecification describes it as a language and an execution engine for\nclient-server applications. It records that GraphQL was created in 2012, that\nwork on it as an open standard began in 2015 and that, since 2019, it has been a\ndeliverable of the GraphQL Specification Project under the Joint Development\nFoundation. The latest release is the September 2025 edition.\n\nEverything starts from the schema a service publishes: a set of types, each with\nnamed fields, and each field with a type of its own. The built-in scalar types\nare `Int`, `Float`, `String`, `Boolean` and `ID`, and a service may add custom\nscalars, such as one for a UUID. Every type is nullable unless it is marked with\n`!`, so a `String!` can never be null, and lists are written in brackets:\n`[LineItem!]!` is a list that is always present and never holds a null. The\nschema can also be queried. Through the introspection fields `__schema` and\n`__type` a client can ask a service what it offers, and developer tools and\nclient libraries are built on that.\n\nThere are three kinds of operation. A query is, in the specification's words, \"a\nread-only fetch\"; a mutation is a write followed by a fetch; and a subscription\nis a long-lived request that delivers data in response to a sequence of events\nover time. On the server each field is backed by a function, usually called a\nresolver, that produces its value. The service first validates an operation\nagainst the schema and only then calls the resolvers for the fields the\noperation selected. The top-level fields of a mutation run one after another\nrather than in parallel, so two writes in the same request cannot race each\nother.\n\nThe specification prescribes neither a transport nor a serialisation format.\nHTTP is the most common choice, and there a GraphQL API is served at a single\nURL, usually ending in `/graphql`, and answers in JSON, the most common format.\nThe client sends a POST whose JSON body carries the `query` text and, where\nneeded, its `variables`. A server may also accept GET for queries, but a\nmutation must always be a POST. The response holds the result under `data` and\nanything that went wrong under `errors`. The GraphQL Foundation's guidance on\nall this follows a GraphQL-over-HTTP specification that is still a draft.\n\n## Why it matters\n\nIn most HTTP APIs the server decides what each endpoint returns. A screen that\nneeds an order's status and its customer's name either receives the whole order\nand the whole customer, more than it asked for, or has to make one request per\nresource and stitch the answers together. The specification calls the two\nproblems over-fetching and under-fetching. GraphQL turns the arrangement around:\nthe client asks at the level of single fields and gets exactly those fields\nback, no more. One request can also follow relations, from an order to its line\nitems to its customer, because the request is shaped like the data it will\nreceive.\n\nThe type system pays off twice. Every operation is validated against the schema\nbefore any resolver runs, so a misspelt field or an argument of the wrong type\nis rejected as a whole, before anything has been executed, and tools can catch\nthe same mistakes while the code is still being written. And since a client only\never gets the fields it selected, adding a field costs existing clients nothing.\nThat makes it practical to evolve an API without version numbers: a new field\nappears alongside the old one, the old one is marked `@deprecated` with a\nreason, it stays valid so existing clients do not break, and it is removed once\nno client uses it any more.\n\nThe costs are real, and most come from stepping outside HTTP's own machinery.\nEntities are no longer identified by URLs, and everything goes to one address,\nusually by POST, while it is GET requests that are typically treated as\ncacheable by default. The caching a REST API gets from intermediaries for free\nhas to be rebuilt on purpose. The status code stops telling the whole story,\nbecause a response that carries data alongside errors is still a success at the\nHTTP level. The client now composes requests the server has never seen, so a\nsingle request can ask for a great deal of work, and protecting the server from\nthat is the service's job, not something GraphQL does for it. Per-field\nresolvers are easy to write but, written naively, chatty with the database\nbehind them.\n\n## What it looks like in practice\n\nA small part of a schema for orders, each with line items and a customer:\n\n```graphql\ntype Query {\n  order(id: ID!): Order\n}\n\ntype Order {\n  id: ID!\n  status: String!\n  items: [LineItem!]!\n  customer: Customer\n}\n\ntype LineItem {\n  name: String!\n  quantity: Int!\n}\n\ntype Customer {\n  name: String!\n}\n```\n\nA screen that shows the status, the line items and the customer's name sends\nthis operation to `/graphql` in the body of a POST, with `{\"id\": \"7421\"}` as its\nvariables:\n\n```graphql\nquery OrderSummary($id: ID!) {\n  order(id: $id) {\n    status\n    items {\n      name\n      quantity\n    }\n    customer {\n      name\n    }\n  }\n}\n```\n\nSuppose the order and its items resolve but the service behind `customer` is\ndown. The response still carries everything that could be produced. The failed\nfield comes back null, and an entry in `errors` says what went wrong, where in\nthe document it happened (line 8, column 5 is `customer`) and which path in the\nresponse it affects:\n\n```json\n{\n  \"data\": {\n    \"order\": {\n      \"status\": \"open\",\n      \"items\": [{ \"name\": \"notebook\", \"quantity\": 2 }],\n      \"customer\": null\n    }\n  },\n  \"errors\": [\n    {\n      \"message\": \"Customer service unavailable\",\n      \"locations\": [{ \"line\": 8, \"column\": 5 }],\n      \"path\": [\"order\", \"customer\"]\n    }\n  ]\n}\n```\n\nBecause `customer` is declared nullable, the damage stops at that field. Had it\nbeen `Customer!`, the error would have propagated to the parent, and the whole\norder would have come back as null. And because `data` is not null, the server\nanswers with a 2xx status even though there is an error: HTTP has no status code\nfor partial success. A client that looks only at the status code will treat this\nanswer as complete.\n\nThe opposite design, in which the server owns the shape of every response, is\nthe one a project in this site's portfolio built. In its\n[JSON passthrough from Postgres to the API](/portfolio/designed-a-json-passthrough-from-postgres-to-api/),\nPostgreSQL functions assemble the whole response as JSON and the Go handler\nforwards it untouched, so changing what a function returns changes what the\nclient receives without anyone editing a line of handler code. There the\nfrontend depends directly on the shape the database gives it. In GraphQL the\nclient names the fields, and the server must be ready to resolve any combination\nof them that the schema allows.\n\n## Where it goes wrong\n\n**One field, a thousand database calls.** Resolvers are small functions, one per\nfield, and a naive service calls them one object at a time. A list of orders\nwith each order's customer then costs one database call for the list and one\nmore for every order in it. The GraphQL Foundation's guidance calls this the N+1\nproblem and points to batching: the loads requested within a short window are\ncollected and sent to the database as a single request, with a tool like\nFacebook's DataLoader.\n\n**One request asks for everything.** Because the client writes the operation,\none document can nest friends of friends many levels deep, repeat an expensive\nfield under a hundred aliases, or pack many operations into a single request.\nEach is valid GraphQL, and each can tie up the server. The defences sit with the\nservice: paginate list fields, reject operations that exceed a maximum depth or\nbreadth before execution starts, cap aliases and batch size, and for finer\ncontrol give fields weights and turn away any operation whose estimated cost\ngoes over budget, a technique known as query complexity analysis that the\nspecification itself gives no rules for. An API that serves only its own clients\ncan go further with trusted documents, so that only operations stored in\nadvance, looked up by hash, may run at all.\n\n**200 OK hides the failure.** A response with errors can still be a 2xx, as in\nthe example above. With the older `application/json` media type the guidance\ngoes further: a 2xx is recommended even when a valid request fails to execute,\nand some legacy servers return 2xx for validation errors too. A client, and the\nmonitoring around it, has to read `errors` and not only the status. The newer\n`application/graphql-response+json` media type makes the status meaningful\nagain, since a valid request that fails to execute then gets a 4xx or 5xx, and\nclients should ask for it in their `Accept` header.\n\n**Caching stops working.** Every operation is a POST to the same URL, so the\ncaches between client and server, a CDN included, see one address and a method\nthey do not cache by default. Sending queries as GET helps, but a long document\ncan exceed the URL length that browsers and CDNs accept. Persisted queries solve\nboth problems: the client sends a hash, and the server looks up the full\ndocument before validating and executing it. Wherever responses are cached over\nHTTP, sensitive ones must be cached privately or not at all.\n\n**A field disappears.** Clients choose fields one by one, so removing or\nrenaming a field breaks every client that still selects it, and not gently: an\noperation that names an unknown field fails validation as a whole, with no data\nat all. The specification keeps deprecated fields valid precisely so that\nexisting clients are not broken. Add the replacement first, mark the old field\n`@deprecated` with a reason that points to the new one, and remove the old field\nonly once nothing selects it any more.\n\n## Further reading\n\n- [GraphQL Specification Versions](https://spec.graphql.org/) — every edition of\n  the specification, from July 2015 to the September 2025 release, plus the\n  working draft: the language, the type system, validation, execution and\n  errors.\n- [Serving over HTTP](https://graphql.org/learn/serving-over-http/) — the single\n  endpoint, POST and GET, the two response media types and the status-code rules\n  for each.\n- [Performance](https://graphql.org/learn/performance/) — GET for queries,\n  persisted queries, the N+1 problem and batching.\n- [Security](https://graphql.org/learn/security/) — trusted documents, depth,\n  breadth and batch limits, query complexity analysis, and introspection and\n  error detail in production.\n\n\u003chttps://engineer.company/glossary/graphql/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"How GraphQL lets the client pick the fields it gets back, what one endpoint costs in caching and status codes, and five ways a GraphQL API goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/graphql/index.gmi","gopher":"https://engineer.company/glossary/graphql/gophermap","html":"https://engineer.company/glossary/graphql/","json":"https://engineer.company/glossary/graphql/index.json","markdown":"https://engineer.company/glossary/graphql/index.md","pdf":"https://engineer.company/glossary/graphql/index.pdf"},"kind":"page","language":"en","title":"What is GraphQL?","url":"https://engineer.company/glossary/graphql/","version":1}