Skip to content

APIs

API paradigms, protocols, and design patterns for building and consuming web services -- from request-response to real-time streaming, from human-authored contracts to machine-generated clients.

← Knowledge Base

Topics

Topic Description
Web Services & APIs REST, GraphQL, gRPC, SOAP, WebSocket, SSE, webhooks, tRPC -- paradigm internals, design patterns, security, versioning, and production operations

Landscape

The API landscape has shifted from a monoculture (REST for everything) to a polyglot ecosystem where teams pick the right 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).

API-first design has become the dominant methodology: define the contract (OpenAPI, GraphQL SDL, Protobuf) before writing implementation code, then generate servers, clients, mocks, and documentation from that single source of truth. This inverts the traditional "code first, document later" approach and eliminates an entire class of client-server mismatch bugs.

Key trends shaping the space:

  • Protocol specialization -- REST remains the default for public APIs, gRPC dominates service-to-service communication in microservices, GraphQL serves complex frontend data requirements, and SSE has become the standard transport for LLM streaming responses.
  • Type safety across the wire -- tRPC, GraphQL code generation, and OpenAPI-generated SDKs are converging on the same 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 -- WebSocket and SSE are no longer niche. AI streaming, collaborative editing, live dashboards, and event-driven architectures have made persistent connections a core infrastructure requirement rather than an optional enhancement.
  • API gateways as platform -- Kong, Envoy, AWS API Gateway, and Cloudflare API Shield have evolved beyond routing into full API lifecycle platforms handling authentication, rate limiting, observability, and schema validation at the edge.

The AsyncAPI Standard

While OpenAPI dominates request-response API description, AsyncAPI has emerged as the equivalent specification for event-driven and message-based APIs -- covering WebSocket, MQTT, Kafka, AMQP, and webhook contracts. Organizations running both synchronous and asynchronous APIs increasingly 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 maturing rapidly within the TypeScript community
Tooling ecosystem REST tooling (OpenAPI, Postman, Swagger UI) is the richest; GraphQL tooling (Apollo, Relay, GraphiQL) is strong; gRPC tooling (buf, grpcurl, Kreya) is catching up
Security standards OWASP API Security Top 10 (2023) provides the canonical threat model; OAuth 2.1, PKCE, and mTLS are converging as the authentication baseline
Specification standards OpenAPI 3.1 (REST), GraphQL SDL (GraphQL), Protocol Buffers (gRPC), AsyncAPI 3.0 (event-driven) cover the major paradigms
Observability OpenTelemetry provides unified instrumentation across all paradigms; gRPC has native interceptor support; GraphQL requires custom span extraction per resolver

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 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. Enables parallel frontend/backend development.
  • Code-first: Write the server implementation, then generate the spec from annotations or introspection. Faster for prototyping but risks drift between implementation and documentation.

The industry is moving decisively toward contract-first, particularly as SDK code generation (openapi-generator, graphql-codegen, buf generate) eliminates the manual cost of maintaining client libraries.

Sources

Questions

  • Will GraphQL Federation v2 become the standard composition layer for microservice APIs, or will simpler gateway-based REST aggregation remain dominant outside the GraphQL ecosystem?
  • As LLM-powered API clients emerge (generating requests from natural language + OpenAPI specs), how will this change API design priorities -- will human-readable URL structures matter less?
  • Is the tRPC model (zero-codegen, TypeScript-only type inference) a ceiling or a template that other language ecosystems will replicate?
  • How will HTTP/3 (QUIC) adoption affect the performance gap between gRPC (currently HTTP/2-native) and REST (mostly HTTP/1.1 in practice)?