GraphQL: The REST API Alternative You Haven’t Heard Of

Facebook released GraphQL to open source this week. It's their internal data query language, used in production for years, now available for everyone. The pitch: instead of REST endpoints with fixed responses, clients query for exactly what they need.

This is radically different from REST, and if it catches on, it changes how we think about APIs entirely.

What GraphQL Is

GraphQL is a query language for APIs. Instead of hitting multiple endpoints:

GET /users/1
GET /users/1/posts
GET /users/1/followers

You write one query:

{
  user(id: 1) {
    name
    posts {
      title
      comments {
        author
      }
    }
    followers {
      name
    }
  }
}

The server returns exactly that structure, nothing more, nothing less. No over-fetching (getting data you don't need). No under-fetching (multiple requests for related data).

The REST Problems GraphQL Solves

REST has well-known pain points:

Over-fetching: Endpoints return all user data when you only need the name. Wasting bandwidth, especially mobile.

Under-fetching: Need user and their posts? Two requests. Need posts with comments? Three requests. Network waterfalls kill performance.

Versioning hell: API v1 returns X. API v2 needs to return Y. Maintain both or break clients.

Documentation drift: APIs documented separately from implementation. They diverge. Developers trust neither.

Multiple clients, multiple needs: Mobile wants less data than web. iOS wants different fields than Android. REST means multiple endpoints or compromise.

GraphQL addresses all of these. Clients request exactly what they need. One request gets everything. Schema is self-documenting. Versioning is unnecessary—add fields, don't break old ones.

How It Works

GraphQL requires server and client changes:

Server defines schema:

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
}

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

This describes what data exists and how it relates. The schema is the contract and the documentation.

Clients query:

query {
  user(id: "1") {
    name
    posts {
      title
    }
  }
}

Server resolves: Each field has a resolver function that fetches data. GraphQL coordinates calling resolvers and assembling the response.

The Complexity Trade-off

GraphQL isn't simpler than REST—it's different complexity:

REST complexity: Multiple endpoints, versioning, documentation, over/under-fetching

GraphQL complexity: Schema design, resolver implementation, query complexity management, caching

You're trading REST's problems for GraphQL's problems. For some use cases, it's a good trade. For others, REST's simplicity wins.

The Caching Challenge

REST APIs cache naturally—URLs map to resources, HTTP caching works automatically.

GraphQL queries are POST requests with query bodies. Standard HTTP caching doesn't work. You need application-level caching, usually via libraries like Apollo or Relay.

This isn't insurmountable but it's additional complexity. The tooling will mature, but right now it's more work than REST's free HTTP caching.

The Relay Connection

Facebook released Relay alongside GraphQL—a React data fetching library designed for GraphQL. Relay colocates data requirements with components:

const UserProfile = Relay.createContainer(UserProfileComponent, {
  fragments: {
    user: () => Relay.QL`
      fragment on User {
        name
        posts {
          title
        }
      }
    `
  }
});

This is powerful—components declare what data they need, Relay fetches it. But Relay is complex and opinionated. Many teams want GraphQL without Relay's overhead.

When GraphQL Makes Sense

GraphQL is valuable for:

APIs serving multiple clients (web, mobile, different apps)
Complex data requirements with nested relationships
Mobile-first applications (bandwidth optimization matters)
Teams wanting self-documenting APIs
Applications with rapidly evolving data needs

GraphQL is overkill for:

Simple CRUD APIs
Internal APIs with one client
Applications where REST caching is critical
Teams wanting simplicity over power

The Adoption Question

GraphQL is days old as open source. The ecosystem is minimal. To use it, you're pioneering:

Building or integrating server implementations
Learning query language and resolver patterns
Handling caching without established solutions
Lacking community knowledge and best practices

Facebook uses it in production successfully, but Facebook has resources and problems most companies don't. Whether GraphQL translates to typical applications is unproven.

The Comparison to Other Approaches

REST: Established, simple, HTTP caching works. But inflexible.

GraphQL: Flexible, powerful, optimized for modern apps. But complex.

Falcor (Netflix): Similar to GraphQL but using JSON instead of query language. Less powerful, simpler.

gRPC: Fast binary protocol for microservices. Different use case than GraphQL.

Each has trade-offs. GraphQL is one option, not universal solution.

Looking Forward

GraphQL's success depends on ecosystem development. Server implementations, client libraries, tooling, documentation—these need maturity before GraphQL becomes mainstream.

The patterns it introduces—client-specified queries, schema-driven APIs, single endpoint—might influence API design even if GraphQL itself doesn't dominate.

For now, GraphQL is promising but experimental. Worth exploring if you have problems it solves. Not worth adopting just because Facebook uses it.

The next year will reveal whether GraphQL is genuinely transformative or just Facebook-scale engineering that doesn't generalize.

Resources:

GraphQL – Official specification and documentation
GraphQL GitHub – JavaScript reference implementation
Relay – Facebook's GraphQL client