What is GraphQL? | Glossary

GraphQL is a way of asking an API for data in which the caller writes a query listing exactly which fields it wants, and the server returns those fields and nothing else. Facebook built it internally in 2012 and released it publicly in 2015; it is now governed by the GraphQL Foundation.

How a GraphQL query is answered

A GraphQL server publishes a schema: a typed description of every object (Product, Customer, Order), its fields and how objects connect. Clients send queries to a single endpoint, usually /graphql, via HTTP POST. A query looks like a skeleton of the answer you want, for example a product's title, price and the first three image URLs. The server walks the schema, calls a resolver function for each field, and replies with JSON in the same nested shape.

Changes are sent as "mutations", and some servers support "subscriptions" for live updates. Because the schema is typed and introspectable, tools can autocomplete queries and catch typos before anything runs.

Example: a product page on Shopify's Storefront API

A custom storefront needs a product's name, price, variant sizes and two photos. With a REST API that might take a product call plus separate image and variant calls, each returning fields the page ignores. With Shopify's Storefront GraphQL API, the front end sends one query naming exactly those fields and gets one compact response. On a phone over a weak connection, fewer and smaller responses make a visible difference.

Does a small business need GraphQL?

Usually only indirectly. You meet it when a platform you use offers it: Shopify, GitHub and many headless CMS products such as Contentful and Hygraph expose GraphQL APIs. If you hire a developer for a headless store or app, they may pick it for the front end. For a site that pulls a few records from one service, REST is simpler and just as good.

GraphQL pitfalls

• Unbounded queries. Clients can request deeply nested data; servers need depth and cost limits or one query can overload them.
• The N+1 problem. Naive resolvers fetch related records one at a time; batching tools like DataLoader exist for this reason.
• Expecting HTTP caching for free. Since most queries are POSTs to one URL, CDNs cannot cache them the way they cache REST GETs without extra setup.
• Reading 200 as success. GraphQL often returns HTTP 200 with an errors array inside, so check the body.

Related terms

• API: the general concept GraphQL implements.
• REST API: the resource-per-URL style it is usually compared with.
• Headless CMS: a common source of GraphQL content.
• Frontend: the code that writes GraphQL queries.