API Architectural Styles — REST, GraphQL, gRPC, SOAP, Webhooks¶

Prerequisites: API Design, Microservices Communication

← Architecture Patterns

Why This Exists¶

API Design covers REST and GraphQL in depth — verb contracts, idempotency, over/under-fetching. Microservices Communication covers when to go synchronous vs. async and picks gRPC as the synchronous internal default. Neither page puts all five styles you'll actually encounter — REST, GraphQL, gRPC, SOAP, and webhooks — side by side and asks the question an interviewer actually asks: "you have five options, why this one, for this caller?"

This page is that comparison. It doesn't re-derive REST or GraphQL mechanics (see API Design for that) — it's the decision layer on top, plus the two styles that page doesn't cover at all: SOAP, which you'll meet at any company with a 15-year-old enterprise integration, and webhooks, which every notification/payment/CI system in this repo already assumes exist but nothing has explained as a pattern with its own failure modes.

The Five Styles¶

flowchart LR
    subgraph REST
        R1[Client] -->|"GET /orders/42"| R2[Server]
        R2 -->|full resource,<br/>server-shaped| R1
    end
    subgraph GraphQL
        G1[Client] -->|"query { order(id:42) { total } }"| G2[Server]
        G2 -->|exactly the fields asked for| G1
    end
    subgraph gRPC
        P1[Client] -->|"GetOrder(id=42)<br/>protobuf, HTTP/2"| P2[Server]
        P2 -->|typed response, binary| P1
    end
    subgraph SOAP
        S1[Client] -->|"XML envelope,<br/>WSDL contract"| S2[Server]
        S2 -->|XML envelope| S1
    end
    subgraph Webhooks
        W2[Server] -.->|"event happened —<br/>POST to client's URL"| W1[Client]
    end

REST — resources, standard verbs¶

Model the API as nouns (/orders/42) manipulated by a fixed HTTP verb set, each with a promised meaning (GET is safe, PUT is idempotent). Full mechanics, the PUT-vs-POST idempotency line, and idempotency keys are in API Design — this page assumes that and moves straight to "when do I pick it."

Best for: public APIs, CRUD-shaped resources, anywhere a browser, a third party, or a CDN/cache needs to reason about a stable URL.

GraphQL — one endpoint, client-shaped queries¶

One endpoint; the client's query specifies exactly the fields it wants across possibly many related resources in one round trip. Full cost breakdown (N+1, cache loss, query-depth limiting) is in API Design.

Best for: clients with diverse, evolving data shapes hitting the same backend — mobile and web pulling different subsets of the same domain model, where the REST alternative is either chronic over-fetching or a proliferating set of bespoke endpoints per screen.

gRPC — typed RPC for service-to-service¶

Not a resource model at all — the client calls a strongly-typed remote function (GetOrder(OrderRequest) → OrderResponse), defined in a .proto schema, serialized as compact binary Protocol Buffers over HTTP/2. Covered as the synchronous-internal default in Microservices Communication.

Best for: internal service-to-service calls at scale, where both ends are your own code (or a partner willing to adopt .proto), and payload size / latency actually matter. Weak fit for anything a browser calls directly — browser gRPC support requires a proxy layer (grpc-web), and you lose curl-and-eyeball debuggability.

SOAP — protocol-level contract, XML envelope¶

A message is an XML "envelope" with a strict, machine-readable contract (WSDL) describing every operation, parameter, and fault. Built in an era (and for an audience — banks, insurers, government, healthcare) where two organizations that don't trust each other's engineering practices needed a contract rigid enough that neither side could accidentally break it, plus first-class support for things REST leaves to convention: transactional messaging (WS-AtomicTransaction), formal security tokens (WS-Security), and guaranteed delivery (WS-ReliableMessaging).

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <auth:Token xmlns:auth="...">eyJhbGciOi...</auth:Token>
  </soap:Header>
  <soap:Body>
    <GetOrder xmlns="http://example.com/orders">
      <OrderId>42</OrderId>
    </GetOrder>
  </soap:Body>
</soap:Envelope>

Best for: you almost never choose SOAP for a new system in 2026 — you inherit it. The realistic scenario is integrating with an enterprise partner (a bank's payment rail, an insurance clearinghouse, a government API) whose only exposed contract is a WSDL file, and the interview-relevant skill is recognizing "we need to wrap this behind an internal REST or gRPC facade" rather than letting SOAP's verbosity leak into the rest of the system.

Why it's heavier, concretely: every SOAP message carries the full envelope/namespace overhead regardless of payload size; there's no lightweight variant. WSDL gives you compile-time-checked clients (genuinely valuable for high-stakes B2B integration) at the cost of a toolchain most teams no longer maintain.

Webhooks — the server initiates¶

Inverted control flow: instead of the client polling "did anything happen yet?", the client registers a URL, and the server pushes an HTTP POST to that URL the moment an event occurs — a payment settled, a CI build finished, a form was submitted.

1. Client registers: POST https://api.example.com/webhooks
     { "url": "https://myapp.com/hooks/stripe", "events": ["payment.succeeded"] }
2. Time passes.
3. Event happens on the SERVER's side (payment settles).
4. Server-initiated: POST https://myapp.com/hooks/stripe
     { "event": "payment.succeeded", "id": "evt_123", "data": {...} }
5. Client's endpoint must respond 2xx quickly, or the sender retries —
   often with backoff, for hours, per its own retry policy.

This is not free of the problems every other async pattern in this repo has — it's at-least-once delivery over HTTP, wearing a different name:

Best for: exactly the notification-system and payment-processing shapes this repo already builds elsewhere — third-party integrations, "notify me when X happens" without polling. It is a push notification pattern, not a request/response style, which is why it doesn't fit the same table as the other four without a caveat: there's no synchronous "response" to a webhook in the way REST/GraphQL/gRPC/SOAP all have one — success is "the receiver's 2xx," nothing more.

Comparison¶

Decision Framework¶

Who's the caller, and what do they need?

Public API, third parties, browsers, "just needs to work everywhere"
  → REST

Internal or first-party client with diverse, evolving screen/data shapes
  → GraphQL

Internal service-to-service, high volume, latency-sensitive, both ends yours
  → gRPC

Integrating with an enterprise/gov/financial partner whose only contract is a WSDL
  → SOAP (wrap it behind an internal REST/gRPC facade immediately)

"Notify me when X happens" instead of polling
  → Webhooks (with signature verification + idempotent receiver, non-negotiably)

Real system: usually more than one of the above, at different boundaries
  → REST at the edge, gRPC internally, GraphQL for a specific
    diverse-client BFF layer, webhooks for outbound async notification —
    see the Hybrid Reality section below

Hybrid Reality¶

Nearly every system in this repo's system-design-exercises already does this without naming it:

flowchart LR
    Mobile["Mobile / Web client"] -->|REST or GraphQL| GW[API Gateway]
    GW -->|gRPC| Orders[Order service]
    GW -->|gRPC| Inventory[Inventory service]
    Stripe["Stripe"] -.->|webhook: payment.succeeded| GW
    Partner["Enterprise partner"] -->|SOAP| Adapter[Legacy adapter service]
    Adapter -->|gRPC| Orders

The public edge and the internal mesh are almost never the same protocol on purpose — see Microservices Communication for the gateway-does-protocol-translation pattern (public REST/GraphQL in, internal gRPC out) that makes this combination coherent instead of accidental.

Interview Questions¶

Key Takeaways¶

Previous: Architecture Patterns | Related: API Design, Microservices Communication