Skip to content

APIs

Domain summary

API paradigms, protocols, and design patterns for building and consuming web services: REST, GraphQL, gRPC (and Connect), SOAP, WebSocket, SSE, WebTransport, webhooks, and tRPC. As of 2026-09 the key contract formats are OpenAPI 3.2.1 (2026-09-10), AsyncAPI 3.1.0 (2026-01-31), the GraphQL September 2025 edition, and Protobuf Edition 2024. OAuth 2.1 is still an IETF draft (-16, 2026-09-03), so OAuth 2.0 plus the RFC 9700 Security BCP is the current authentication baseline.

← Knowledge Base

Topics

Topic What it covers Current versions (checked 2026-09-25) License
Web Services & APIs Vendor-neutral guide to REST, GraphQL, gRPC/Connect, SOAP, WebSocket, SSE, WebTransport, webhooks, and tRPC: internals, specifications, security, versioning, testing, and operations OpenAPI 3.2.1, AsyncAPI 3.1.0, GraphQL September 2025 edition, gRPC core 1.84.0, Protobuf Edition 2024 Concept topic. OpenAPI and AsyncAPI specs: Apache-2.0. gRPC: Apache-2.0. Apollo Router / Federation: Elastic License 2.0

How the Domain Fits Together

The map shows what the Web Services & APIs topic covers, the comparison built on it, and the neighbouring domains each paradigm depends on.

flowchart LR
    subgraph APIS["APIs domain"]
        WS["Web Services and APIs<br/>(topic)"]
        CMP["REST vs GraphQL vs gRPC<br/>(comparison)"]
    end
    WS --> REST["REST + OpenAPI 3.2.1"]
    WS --> GQL["GraphQL<br/>(September 2025 edition)"]
    WS --> GRPC["gRPC + Protobuf<br/>(Edition 2024)"]
    WS --> RT["SSE, WebSocket,<br/>WebTransport"]
    WS --> EV["Webhooks +<br/>AsyncAPI 3.1.0"]
    CMP -.-> REST
    CMP -.-> GQL
    CMP -.-> GRPC
    GRPC -->|"L7 load balancing, mTLS"| SM["Service mesh:<br/>Envoy Gateway, Istio, Linkerd"]
    EV -->|"event contracts"| MSG["Messaging: Kafka"]
    REST -->|"OAuth 2.x / OIDC"| ID["Identity: ZITADEL"]
    GQL -->|"traces and metrics"| OBS["Observability:<br/>OpenTelemetry"]

Comparisons

Comparison Scope
REST vs GraphQL vs gRPC The three main request/response paradigms: contracts, transport, streaming, caching, errors, versioning, security, tooling, and a decision flowchart. Also covers when Connect RPC or tRPC fits better

All comparison notes are listed in the comparisons index.

When to Use Which

The rules below match the decision flowchart in REST vs GraphQL vs gRPC and in Explanation — Protocol Comparison Overview.

Need Reach for
Public or partner API, any client language, HTTP caching REST + OpenAPI
Many first-party frontends with different data shapes, multi-team graph GraphQL (federated if several teams own parts of the graph)
Internal service-to-service calls, streaming, strict contracts gRPC
gRPC-style contracts that browsers must call without a translation proxy Connect RPC
One TypeScript team owning client and server tRPC
Server-to-client push (feeds, LLM token streaming) SSE
Bidirectional real-time traffic (chat, collaboration) WebSocket (WebTransport for datagrams over HTTP/3)
Notifying external systems about events Webhooks (Standard Webhooks signatures), described with AsyncAPI
Existing enterprise WSDL contract SOAP

It is not either-or

Real platforms combine paradigms: REST at the public edge, GraphQL for first-party frontends, gRPC between internal services, SSE or WebSocket for real-time features, and webhooks for integrations. See Explanation — Choosing the Right API Paradigm.

Landscape

The API landscape shifted from a monoculture (REST for everything) to a polyglot ecosystem. Teams now pick the paradigm per boundary. The spectrum runs from simple request-response (REST, gRPC), through query-driven flexibility (GraphQL, tRPC), to persistent real-time channels (WebSocket, SSE, WebTransport).

API-first design is the common methodology. Define the contract (OpenAPI, GraphQL SDL, Protobuf) before you write implementation code. Then generate servers, clients, mocks, and documentation from that single source of truth. This inverts the traditional "code first, document later" workflow and removes a whole class of client-server mismatch bugs.

Key trends:

  • Protocol specialization -- REST stays the default for public APIs. gRPC is the usual choice for internal service-to-service calls. GraphQL serves complex frontend data requirements. SSE is the de facto transport for LLM token streaming.
  • Type safety across the wire -- tRPC, GraphQL code generation, and OpenAPI-generated SDKs converge on one goal: compile-time guarantees that client calls match server contracts. The difference is scope. tRPC is TypeScript-only, GraphQL spans ecosystems, and OpenAPI covers any HTTP API.
  • Real-time as a first-class concern -- AI streaming, collaborative editing, live dashboards, and event-driven architectures made persistent connections core infrastructure. OpenAPI 3.2 added streaming media types (itemSchema for SSE and JSON Lines) to describe them.
  • API gateways as platform -- Kong, Envoy, AWS API Gateway, and Azure API Management go beyond routing. They handle authentication, rate limiting, observability, and schema validation at the edge. See Reference — API Gateway Comparison.
  • New HTTP standards -- the HTTP QUERY method (RFC 10008, June 2026) standardizes a safe, idempotent request with a body, and the Deprecation header (RFC 9745, March 2025) joins Sunset (RFC 8594) for API lifecycle signalling.

The AsyncAPI standard

OpenAPI dominates request-response API description. AsyncAPI (3.1.0, 2026-01-31) is the equivalent specification for event-driven and message-based APIs. It covers WebSocket, MQTT, Kafka, AMQP, and webhook contracts. Organizations that run both synchronous and asynchronous APIs maintain both specs side by side.

Evaluation

Dimension Assessment
Paradigm maturity REST and SOAP are fully mature. GraphQL and gRPC are production-stable with large ecosystems. tRPC is at v11 (11.19.0, 2026-09-16). WebTransport is emerging: its IETF protocol is still a draft
Tooling ecosystem REST tooling (OpenAPI, Spectral, Prism, Swagger UI, Redoc, Scalar) is the richest. GraphQL tooling (Apollo, GraphQL Yoga, graphql-codegen, GraphiQL) is strong. gRPC tooling (buf, grpcurl, Connect) covers linting, breaking-change checks, and codegen
Security standards OWASP API Security Top 10 (2023 edition, still the latest) is the canonical threat model. OAuth 2.0 with the RFC 9700 Security BCP (PKCE, no implicit grant, sender-constrained tokens via DPoP or mTLS) is the authentication baseline. OAuth 2.1 remains a draft
Specification standards OpenAPI 3.2.1 (REST), GraphQL September 2025 edition (GraphQL), Protobuf Edition 2024 (gRPC), AsyncAPI 3.1.0 (event-driven), plus Arazzo 1.1.0 and Overlay 1.1.0 from the OpenAPI Initiative
Observability OpenTelemetry provides unified instrumentation across all paradigms. gRPC has native interceptor support. GraphQL needs per-resolver span extraction

Key Concepts

Request-Response vs Streaming Spectrum

APIs fall along a spectrum from pure request-response to persistent streaming:

Pattern Paradigms Use Case
Synchronous request-response REST, gRPC unary, SOAP CRUD operations, form submissions, data queries
Query-driven request-response GraphQL, tRPC Complex data fetching with client-controlled shape
Server push (half-duplex) SSE, gRPC server streaming LLM token streaming, live feeds, notifications
Full-duplex streaming WebSocket, gRPC bidirectional, WebTransport Chat, collaborative editing, gaming
Event-driven callbacks Webhooks Payment confirmations, CI/CD notifications, third-party integrations

Contract-First vs Code-First

  • Contract-first (API-first): Write the OpenAPI spec, GraphQL SDL, or Protobuf definition before any implementation. Generate server stubs, client SDKs, mock servers, and documentation from the contract. This enables parallel frontend/backend development. See How-to Guides — API-First Design.
  • Code-first: Write the server implementation, then generate the spec from annotations or introspection. This is faster for prototyping but risks drift between implementation and documentation.

SDK code generation (openapi-generator, graphql-codegen, buf generate) removes most of the manual cost of maintaining client libraries, which favours contract-first for any API with more than one consumer.

Sources

Open Questions

  • Will the GraphQL Foundation's Composite Schemas spec (Stage 0: Preliminary as of 2026-09) displace Apollo Federation 2 as the composition layer, or will Federation-compatible Apache-2.0 routers (Cosmo, Hive Gateway) keep Apollo's protocol as the de facto standard? See Explanation — Federation.
  • As LLM-powered API clients generate requests from natural language plus OpenAPI specs, how will API design priorities change -- will human-readable URL structures matter less than rich spec descriptions?
  • Is the tRPC model (zero-codegen, TypeScript-only type inference) a ceiling or a template that other language ecosystems will replicate?
  • Will core gRPC adopt HTTP/3? gRFC G2 exists, but only grpc-dotnet implements it; grpc-go, grpc-java, and gRPC core had no official HTTP/3 transport as of 2026-09. See Explanation — HTTP/3.
  • When will OAuth 2.1 become an RFC? Track the datatracker page.