API styles

An API style is the set of rules a client follows to ask a server for data. Three styles cover most real systems: REST, gRPC and GraphQL. Each can answer the same question. They differ in what the client has to know and what the server has to guarantee.

The big idea

Take one question: "get a user with their three most recent orders." Each style asks it differently.

• REST models things as resources, such as users/u_123, and fetches them with HTTP verbs.
• gRPC exposes typed methods, such as GetUser, with binary messages over HTTP/2.
• GraphQL exposes one endpoint and a typed schema. The client asks for exactly the fields it wants.

Pick the style that fits your callers. Don't pick the one you read about most recently.

Walking through it

REST sends a path and query, and the server decides the response shape:

GET /v1/users/u_123?expand=recent_orders&recent_orders_limit=3 HTTP/1.1
Host: api.example.com

GraphQL sends a query, and the response contains only the requested fields:

query {
  user(id: "u_123") {
    name
    recentOrders(first: 3) { id totalCents }
  }
}

The main trade-offs:

GraphQL has a cost that REST doesn't. Resolvers run once per field. Fifty posts, each with an author lookup, can turn one query into 1 + 50 database calls. This is the N+1 problem, and batching the lookups fixes it.

Many companies use all three. REST serves the public API, gRPC connects internal services, and GraphQL sits in front as a backend-for-frontend for their own apps.

Common mistakes

• gRPC for a public API. Outside developers expect JSON they can call with curl. gRPC needs generated clients.
• Assuming GraphQL caches like REST. A single /graphql POST URL gives HTTP caches nothing to key on.
• Forgetting the N+1 problem. A GraphQL schema that looks simple can issue dozens of database queries per request.

Check yourself

1. Why is REST easier to put behind a CDN than GraphQL? REST GETs have a URL that caches can key on, while GraphQL usually sends everything as a POST to one URL.
2. When is gRPC the better choice? For internal service-to-service calls where typed contracts, compact encoding and streaming matter.

Key takeaways

• The three styles answer the same question with different trade-offs.
• REST suits public and web APIs. gRPC suits internal traffic. GraphQL suits many clients with different data needs.
• GraphQL moves complexity to the server, including N+1 queries and caching.

Further learning

The gRPC documentation covers the service and message model in depth.

Next, read about safe methods and idempotency.