API Styles: REST, RPC and gRPC, GraphQL

REST: resources and verbs

REST (Representational State Transfer) models an API as resources (nouns) at URLs, acted on with standard HTTP methods (verbs):

REST's strength is that it reuses HTTP: status codes, caching headers, authentication, tooling, CDNs and proxies all work out of the box, and any language can call it. Its weaknesses are over-fetching (the endpoint returns fields you do not need) and under-fetching (you need several calls to build one screen).

RPC and gRPC: calling functions remotely

Remote procedure call (RPC) styles model an API as functions: CreateOrder, GetUser, ChargeCard. The client calls them almost as if they were local.

gRPC, created at Google and now an open-source project, is the most common modern RPC framework. You describe services and messages in a .proto file; code generators produce typed clients and servers in many languages. By default messages are encoded with Protocol Buffers, a compact binary format, and sent over HTTP/2, which allows streaming in both directions.

gRPC shines between your own services: strict contracts catch mismatches at build time, binary messages are small and fast, and deadlines and streaming are built in. It is less convenient for browsers (which need a proxy layer such as gRPC-Web) and harder to inspect by hand than JSON.

GraphQL: the client asks for what it needs

GraphQL, created at Facebook and open-sourced in 2015, exposes one endpoint and a typed schema. The client sends a query describing exactly the data it wants, possibly across several related objects, and gets exactly that back in one round trip.

class OrderPage {
    // REST: three calls, each returning whole objects.
    static final String[] REST_CALLS = {
        "GET /orders/42",
        "GET /orders/42/items",
        "GET /customers/7"
    };

    // GraphQL: one call, only the fields the page shows.
    static final String GRAPHQL_QUERY = """
        query {
          order(id: 42) {
            status
            total
            items { name quantity }
            customer { name }
          }
        }
        """;
}

# REST: three calls, each returning whole objects.
REST_CALLS = [
    "GET /orders/42",
    "GET /orders/42/items",
    "GET /customers/7",
]

# GraphQL: one call, only the fields the page shows.
GRAPHQL_QUERY = """
query {
  order(id: 42) {
    status
    total
    items { name quantity }
    customer { name }
  }
}
"""

• Good: no over- or under-fetching, one round trip per screen, a self-documenting schema; ideal when many different clients (web, iOS, Android) need different shapes of data.
• Costs: HTTP caching is harder (everything is a POST to one URL), a single query can ask for a huge amount of work (limit query depth and cost), and naive resolvers cause the N+1 query problem (one database query per item); batching tools such as DataLoader fix it.

Choosing a style

Pagination and versioning

Two habits keep any API healthy as it grows.

Paginate with cursors

Never return an unbounded list. Offset pagination (?page=500) is simple but slow on large tables (the database still walks past every skipped row) and skips or repeats items when rows are added between pages. Cursor pagination returns an opaque token pointing at the last item seen; the next request asks for items after it, which uses an index and stays fast and stable.

import java.nio.charset.StandardCharsets;
import java.util.Base64;

class Cursor {
    static String encode(long lastId) {
        String raw = "id:" + lastId;
        return Base64.getUrlEncoder().withoutPadding()
            .encodeToString(raw.getBytes(StandardCharsets.UTF_8));
    }

    static long decode(String cursor) {
        String raw = new String(Base64.getUrlDecoder().decode(cursor), StandardCharsets.UTF_8);
        if (!raw.startsWith("id:")) {
            throw new IllegalArgumentException("bad cursor");
        }
        return Long.parseLong(raw.substring(3));
    }
}

// SELECT * FROM orders WHERE id > :lastId ORDER BY id LIMIT 50

import base64

def encode_cursor(last_id):
    raw = f"id:{last_id}".encode()
    return base64.urlsafe_b64encode(raw).decode().rstrip("=")

def decode_cursor(cursor):
    padded = cursor + "=" * (-len(cursor) % 4)
    raw = base64.urlsafe_b64decode(padded).decode()
    if not raw.startswith("id:"):
        raise ValueError("bad cursor")
    return int(raw[3:])

# SELECT * FROM orders WHERE id > :last_id ORDER BY id LIMIT 50

Version without breaking clients

Mobile apps stay installed for years, so old clients keep calling old shapes. Add fields freely, but never remove or rename them in place. For breaking changes, publish a new version (/v2/orders, a version header, or a new GraphQL field) and retire the old one only when traffic to it is gone.

Common mistakes

• Designing REST URLs around actions (/createOrder, /getUserById) instead of resources.
• Returning unbounded lists that work in development and time out in production.
• Exposing GraphQL publicly without query depth and cost limits.
• Making breaking changes to an API that installed mobile apps still call.

Interview questions

Try answering out loud before you open each one.

Check yourself

Related topics

• HTTP and HTTPSNetworking and Communication
• Monolith vs MicroservicesApplication Layer
• Real-Time: Polling, Long Polling, WebSockets and SSENetworking and Communication

Further reading

• gRPC introduction grpc.io
• Introduction to GraphQL graphql.org
• Architectural Styles and the Design of Network-based Software Architectures (REST, chapter 5) Roy Fielding, 2000