API Architectural Styles

Updated June 3, 2026

Magic Magnets Team

8 min read

REST (Representational State Transfer)

algobase.dev

REST models everything as resources, identified by URLs. HTTP methods define the action: GET /users/123 fetches user 123 (idempotent, cacheable by default), POST /users/123/orders creates an order belonging to that user. The URL structure maps to the resource hierarchy. REST is the standard for public APIs — Stripe, GitHub, and Twitter all use it.

1 / 1

REST resource model — GET/POST/PUT/DELETE on /users/:id

REST is the dominant standard for public web APIs. It models everything as resources (nouns) and uses HTTP methods as verbs to operate on them. A GET /users/123 fetches a user. A PATCH /users/123 updates one. This maps cleanly onto HTTP semantics, which means REST APIs get built-in caching, well-understood status codes, and broad tooling support almost for free.

The trade-off is that REST endpoints are designed around fixed resource shapes. Clients frequently receive more fields than they need (over-fetching) or must make several sequential requests to assemble related data (under-fetching). The Stripe API and Twitter API are canonical examples.

Quiz Time

A REST API client needs a user's name, email, and their last 5 orders in a single render. With a typical REST design, what problem does this cause?

GraphQL

algobase.dev

GraphQL exposes a single POST /graphql endpoint. The client sends a query specifying exactly which fields it needs. A mobile client on a slow network can ask for just name and avatar; a dashboard can ask for name, email, role, createdAt, and posts in one request. The server resolves only the data actually requested, pulling from databases and caches independently. Used by GitHub v4 and Facebook (the inventor). The tradeoff: HTTP-level caching does not work, and the N+1 resolver problem requires careful batching.

1 / 1

GraphQL single endpoint — client query returns exact field shape

Invented at Facebook, GraphQL was a direct response to REST's over-fetching problem. Rather than scattering resources across many URLs, GraphQL exposes a single endpoint (typically /graphql) and lets the client describe exactly the fields it wants. The server returns that shape and nothing more.

You send a POST request with a query payload:

query {
  user(id: 123) {
    name
    email
    recentOrders(limit: 5) {
      total
    }
  }
}

This makes GraphQL particularly effective for mobile clients on constrained networks, where trimming payload size has a real impact. The cost is caching complexity. A single endpoint means HTTP cache keys are meaningless, so caching has to be implemented at the application layer. Deeply nested or poorly written queries can also trigger the N+1 problem on the server. GitHub API v4 and the Shopify Storefront API both use GraphQL.

Quiz Time

GraphQL exposes a single endpoint, which means standard HTTP caching (e.g. CDN, browser cache) works just as well as it does for REST.

gRPC

algobase.dev

gRPC is action-oriented, not resource-oriented. You call methods (BillingService.Charge, not POST /charges). Services are defined in .proto files, and the compiler generates type-safe client and server stubs in any language. Data is serialized to compact binary Protobuf — no field names on the wire, just values indexed by field numbers. All calls run over HTTP/2, which multiplexes multiple in-flight RPCs on a single TCP connection. This is the dominant pattern for internal microservice communication at companies like Netflix, Uber, and Google.

1 / 1

gRPC binary RPC call — service definition, stub generation, HTTP/2 transport

Developed at Google, gRPC abandons the resource model entirely. Rather than fetching nouns, you invoke remote procedures: named actions defined in a .proto schema file. The toolchain generates typed client stubs in your language of choice, so a call looks identical to a local function call at the source level:

// The client simply calls a generated function
const response = await client.UpdateUserEmail({ id: 123, email: "new@email.com" });

Under the hood, gRPC serializes messages with Protobuf (a compact binary format) and transmits them over HTTP/2. Binary payloads are smaller than equivalent JSON and deserialize faster. HTTP/2 multiplexing also enables native bi-directional streaming. The strict schema enforced by the .proto file acts as a compile-time contract between services. A breaking change on the server will fail the client build before it ever reaches production.

The limitations are real: web browsers cannot speak gRPC directly without a translation proxy (grpc-web), and binary payloads are opaque to standard debugging tools. gRPC is the right choice for internal microservice-to-microservice communication where you control both ends. It is rarely the right choice for public-facing APIs. Uber and Netflix use it extensively across their backend infrastructures.

Quiz Time

What does a .proto file provide in a gRPC system?

Quiz Time

A web browser can call a gRPC service directly without any additional infrastructure.

Webhooks

Most APIs are pull-based: the client asks the server for data. Webhooks invert this. The server pushes data to the client when an event occurs.

Instead of polling an endpoint every few seconds asking whether a payment has completed, you register a URL with the payment provider. When the payment settles, the provider POSTs the result to that URL. This eliminates polling traffic entirely and makes event-driven pipelines straightforward to build.

The operational requirement is that the client must expose a publicly reachable HTTPS endpoint. If that endpoint is down when the webhook fires, the event can be lost unless the sender implements retry logic with exponential backoff. Designing for idempotency on the receiving end, so that replayed events do not cause duplicate processing, is standard practice.

Quiz Time

Which scenario is webhooks specifically designed to solve?

Summary

REST is the reliable default for public APIs. It maps operations onto HTTP verbs and resource URLs, inherits HTTP caching, and is understood by every HTTP client in existence. GraphQL is the right tool when frontend teams need precise control over payload shape, particularly on mobile or slow connections. It comes at the cost of more complex server-side query execution and caching. gRPC trades human-readability for performance and contract enforcement. It excels at internal microservice communication where both ends are owned by the same team. Webhooks are not a query mechanism at all. They are an event-notification pattern that eliminates polling for asynchronous, event-driven workflows.

REST API Design

How helpful was this content?

Comments

0/2000

Saved on this device only