In practice
I pick GraphQL when the screens of an app need different slices of the same data and I do not want to multiply endpoints. It is in the stack of Kuma.de and, in the Code & Pepper team, Little Birdie. For a simple API I stay with REST.
What is GraphQL?
GraphQL is a query language for APIs and a server-side runtime, built on a type system you define yourself. You describe a service with a schema: types and their fields, and for each field you write a function that supplies the data. GraphQL is not tied to any database or storage engine, because it rests on your code.
A client asks for exactly the fields it needs and gets a response in the same shape, in a single request. The server first checks the query against the schema and only then runs it. It also lets you query the schema itself, called introspection, which developer tools build on. It usually sits at one address instead of a separate one for every resource.
- Kind
- A query language and a runtime
- Schema
- Types and fields, a function per field
- Response
- Only the fields asked for, in one request
- Entry point
- Usually a single address for the whole API
How I work with GraphQL
I start from the screens, not the schema. First I list what data each screen needs, because the schema should serve the client, not mirror the structure of the database.
A schema seen from the screen
I name types and fields the way the app talks about them, not the way the tables are named. The schema is a contract between frontend and backend, so I keep it in the repository and change it through review. Fields marked deprecated stay until nothing uses them, so an older release of a mobile app keeps working.
The client picks the fields
A query lists the fields a screen needs, so I send no excess. On Kuma.de each screen loads only the data it needs.
Permissions and limits
I check permissions in the logic called from field functions, per field. Before production I set query limits and decide about introspection, because both belong to security.
When it fits, and when it doesn't
GraphQL makes sense when many clients ask for different slices of the same data.
A good fit when
- A web app and a mobile app that share one API but need different fields.
- Screens that draw on several sources, which the client prefers to fetch in one query.
- A Strapi backend that exposes GraphQL through a plugin.
- An API whose schema should be an explicit contract between the frontend and backend teams.
Not a fit when
- A simple API with a few resources that REST covers fully.
- A team that will not maintain a schema and field functions.
- A public API where caching by URL matters, because in GraphQL the address does not identify an object.
When the frontend and backend live in one TypeScript project, I look at tRPC, which I describe separately. For simple resources REST is enough.
Frequently asked questions
A web and a mobile app on one API?
Tell me which screens you need and where the data comes from, and I will tell you whether GraphQL pays off or plain REST does the job.