GraphQL

Technologies

What is GraphQL?

GraphQL is a query language and runtime for APIs. Facebook developed it in 2012 and released it as open source in 2015. With a REST API, each endpoint returns a fixed structure. With GraphQL, the client describes which fields it needs, and the server returns exactly those, in one request. A schema describes every type and field the API offers.

Core concepts

  • Schema and types: the schema defines every type and field, and each query is checked against it before it runs.

  • Queries: read data. The shape of the query matches the shape of the response.

  • Mutations: change data.

  • Subscriptions: receive updates when data changes.

  • Introspection: the API can describe its own schema. Tools use this for documentation and autocomplete.

  • Directives: annotations such as @include and @skip that change how a query is executed.

  • One endpoint: all requests go to the same URL.

When GraphQL fits

  • Several clients, one backend: a website and a mobile app request different fields from the same API.

  • No unused data: the client receives only the fields it asked for.

  • Adding without breaking: new fields and types can be added without affecting existing queries.

Trade-offs

GraphQL adds work on the server side. HTTP caching is harder than with REST, because most requests go to one endpoint. Without limits on query depth or cost, a client can send a query that is very expensive to run. For a simple API with one client, REST is often the simpler choice.

Our experience

In a website relaunch we used GraphQL to load technical documentation into the site and keep it up to date automatically.

Need help with GraphQL?

Our team has extensive experience working with GraphQL. Let us help you build, integrate, or optimize your project.

Explore our services