GraphQL

Explanation

GraphQL (developed by Facebook in 2012, open-sourced in 2015) addresses REST's fixed-endpoint model with a single flexible endpoint. Instead of the server defining what data each endpoint returns, the client writes a query describing the exact fields it needs. The server's schema defines what data is available; the client composes queries from that schema. One request can fetch deeply nested, related data that would require multiple REST requests. The three GraphQL operations are: query (read data), mutation (write data — create, update, delete), and subscription (real-time updates via WebSocket). Every GraphQL request goes to the same endpoint (POST /graphql), with the operation in the request body as a JSON string. GraphQL solves two REST problems: over-fetching (REST returns entire user objects when you only need the name) and under-fetching (getting a user's posts requires a second request to GET /users/42/posts). With GraphQL, one query can request user.name and user.posts[0].title. This reduces payload size and eliminates round trips. Trade-offs: GraphQL's flexibility makes caching harder (no URL-based caching; requires client-side caching like Apollo Client), query complexity can be expensive to resolve on the server, and schema design requires more upfront thought. REST is simpler for public APIs, CRUD operations, and teams unfamiliar with GraphQL. GraphQL excels for complex, interconnected data models and mobile clients where bandwidth is limited.

Code Example

// GraphQL query vs REST comparison

// REST: multiple requests for user + their posts
// GET /users/42       → user data
// GET /users/42/posts → posts (second round trip)

// GraphQL: one query, exactly what you need
const query = `
  query GetUserWithPosts($id: ID!) {
    user(id: $id) {
      name
      email
      posts(limit: 5) {
        title
        createdAt
      }
    }
  }
`;

const response = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables: { id: '42' } }),
});
const { data, errors } = await response.json();

// GraphQL mutation (create a post)
const mutation = `
  mutation CreatePost($input: PostInput!) {
    createPost(input: $input) {
      id
      title
      createdAt
    }
  }
`;

Why It Matters for Engineers

GraphQL is used by Facebook, GitHub, Shopify, Twitter, and many other major platforms. Knowing how to work with GraphQL APIs — and when to recommend GraphQL vs REST — is a practical skill for full-stack engineers. Many developer tools and third-party APIs (GitHub's API v4, Shopify's Storefront API) are GraphQL-only. Understanding GraphQL's trade-offs also sharpens your API design judgment. When a client team complains about too many API calls or getting unused data, GraphQL is often the right architectural response. When a small team wants simplicity and cacheability, REST is right. Knowing which to choose requires understanding both.