GraphQL

Facebook's mobile app in 2012 was painfully slow. The news feed required data from multiple REST endpoints: posts, comments, likes, user profiles, photos, shared links. Each screen loaded by making 5-15 separate API calls. On a 3G mobile network with 300ms round-trip latency, that is 1.5 to 4.5 seconds of just waiting for network round trips, before any rendering.

Worse, each endpoint returned way more data than the mobile app needed. The user profile endpoint returned 50 fields; the feed only needed the name and avatar. The post endpoint returned full HTML content; the feed only needed the first 140 characters. Wasted bandwidth on metered mobile connections.

Lee Byron and Dan Schafer at Facebook built GraphQL in 2012 to solve both problems simultaneously. Instead of multiple endpoints returning fixed data shapes, a single endpoint accepts a query that specifies exactly which fields to return. One request, one response, no over-fetching, no under-fetching.

# One query replaces 3 REST calls
query {
 user(id: "123") {
 name
 avatar
 posts(first: 5) {
 title
 likeCount
 comments(first: 3) {
 text
 author { name }
 }
 }
 }
}

This single query fetches the user, their recent posts, and the first few comments on each post. In REST, that would require GET /users/123, GET /users/123/posts, and GET /posts/{id}/comments for each post. One round trip instead of many.

GitHub migrated from REST v3 to GraphQL v4 in 2016. Shopify runs their entire storefront API on GraphQL. Airbnb, Yelp, The New York Times, and thousands of others adopted it. It is not a replacement for REST everywhere, but for complex data fetching on mobile, it is transformative.

GraphQL has three operation types:

Queries (read data):

query {
 product(id: "SKU-456") {
 name
 price
 inStock
 reviews(rating: { gte: 4 }) {
 text
 author { name }
 }
 }
}

The client specifies exactly which fields it wants. The server returns exactly those fields, nothing more.

Mutations (write data):

mutation {
 createOrder(input: {
 productId: "SKU-456",
 quantity: 2
 }) {
 id
 total
 status
 }
}

Mutations modify data and return the result. Like REST POST/PUT/DELETE but with the same flexible field selection.

Subscriptions (real-time):

subscription {
 orderStatusChanged(orderId: "123") {
 status
 updatedAt
 }
}

Subscriptions push updates to the client over WebSocket when data changes. GitHub uses subscriptions to push issue and PR updates in real time.

The schema defines everything. Every type, every field, every argument is declared in a typed schema. The server must implement what the schema declares. The client can only query what the schema allows. This is the contract.