What is GraphQL?
GraphQL is a query language for APIs that lets clients request exactly the data they need — no more, no less. Created at Facebook in 2012 and open-sourced in 2015, it has become a popular alternative to REST for applications that deal with complex, interconnected data.
The Problem GraphQL Solves
REST APIs typically expose fixed endpoints that return predetermined data shapes. A mobile client that only needs a user's name still downloads the entire user object. Conversely, a dashboard may need data from five endpoints to render a single page, leading to multiple round trips. GraphQL solves both problems by giving the client control over the response shape.
How Queries Work
A GraphQL query describes exactly the fields you want. The server returns a JSON object that mirrors the query structure:
{
user(id: "42") {
name
email
posts { title }
}
}
The response contains only name, email, and the title of each post — nothing else. You can validate and format the resulting JSON with the JSON Formatter to inspect the payload quickly.
Mutations: Writing Data
While queries read data, mutations change it. A mutation looks similar to a query but signals a write operation:
mutation {
createPost(title: "Hello", body: "World") {
id
createdAt
}
}
Mutations return data too, so the client immediately knows the state of the created resource without a second request.
Schema and Type System
Every GraphQL API is defined by a schema written in the Schema Definition Language (SDL). The schema declares types, queries, and mutations:
type User {
id: ID!
name: String!
email: String
posts: [Post!]!
}
type Query {
user(id: ID!): User
}
The ! marks non-nullable fields. This strong type system provides built-in documentation and enables excellent tooling — editors can autocomplete fields and catch errors before runtime.
GraphQL vs REST
REST uses multiple endpoints (/users, /users/42/posts) and HTTP verbs to define operations. GraphQL uses a single endpoint (/graphql) where the query itself defines the operation. REST is simpler for CRUD resources; GraphQL shines when clients have diverse data needs or when the data graph is deeply nested. Use the cURL Converter to test either style of API from the command line.
Subscriptions: Real-Time Data
GraphQL also supports subscriptions that push data to clients over a persistent connection (usually WebSockets). This is ideal for chat apps, live dashboards, and collaborative editing. You can test WebSocket connections with the WebSocket Tester to verify your subscription endpoint is working.
When to Use GraphQL
GraphQL is a strong choice when multiple clients (web, mobile, IoT) consume the same API with different data needs, when the data model has many relationships, or when you want to reduce over-fetching. It adds complexity — caching is harder than REST, and you need to guard against expensive queries. For simple CRUD services, REST remains a perfectly good choice.