What is GraphQL?

Definition

GraphQL is an open-source query language and runtime developed by Facebook (now Meta) in 2012 and released publicly in 2015. Unlike REST, where the server defines the response structure, GraphQL lets clients specify exactly what data they need in a single request.

GraphQL uses a strongly typed schema to define available data and operations. Clients send queries that mirror the shape of the response they want, and the server returns exactly that data - nothing more, nothing less.

Key Concepts

• Schema: A type system that defines all available data, queries, and mutations. Written in Schema Definition Language (SDL).
• Queries: Read operations that fetch data. Clients specify the fields they need.
• Mutations: Write operations that modify data (create, update, delete).
• Subscriptions: Real-time data updates via WebSocket connections.
• Resolvers: Server-side functions that fetch the data for each field in a query.
• Single endpoint: All operations go through one URL (typically /graphql), unlike REST's multiple endpoints.

When to Use GraphQL

GraphQL shines in specific scenarios:

• Complex data relationships: When entities have many nested relationships that clients need to traverse.
• Multiple client types: Mobile apps may need less data than web apps - GraphQL lets each client request what it needs.
• Rapid frontend development: Frontend teams can iterate on data requirements without backend changes.
• API aggregation: Combining data from multiple backend services into a single API layer.

Consider REST for simpler APIs, public APIs that benefit from caching, or when your team is more familiar with REST patterns.

Code Example

# GraphQL Query Example
query {
  user(id: "123") {
    name
    email
    posts(limit: 5) {
      title
      publishedAt
      comments {
        text
        author {
          name
        }
      }
    }
  }
}

# Single request returns exactly what you need
# No over-fetching, no multiple round trips

Frequently Asked Questions

Is GraphQL replacing REST?

No. GraphQL and REST serve different use cases. REST remains dominant for simple, resource-oriented APIs and is easier to cache. GraphQL excels with complex data requirements and multiple client types. Many companies use both: REST for public APIs and GraphQL for internal consumption.

What are the downsides of GraphQL?

GraphQL adds complexity: you need a schema, resolvers, and often a dedicated gateway. Caching is harder than REST (no HTTP-level caching). The N+1 query problem requires careful resolver design. Rate limiting is more complex since one query can be arbitrarily expensive.