Skip to content

Web Services & APIs

Summary

A vendor-neutral guide to web API paradigms: REST, GraphQL, gRPC (and Connect), SOAP, WebSocket, SSE, WebTransport, webhooks, and tRPC. It covers how each works, which specification governs it, how to secure, version, test, and operate it, and which versions are current. As of 2026-09 the key contract formats are OpenAPI 3.2.1, AsyncAPI 3.1.0, the GraphQL September 2025 edition, and Protobuf Edition 2024. OAuth 2.1 is still an IETF draft, and the new HTTP QUERY method (RFC 10008) became a standard in June 2026.

Key Facts

Fact Value
Scope Concept topic (API paradigms and standards), not a single product
Latest Version (REST contract) OpenAPI 3.2.1 (2026-09-10). 3.2.0 released 2025-09-19
Latest Version (event-driven contract) AsyncAPI 3.1.0 (2026-01-31)
Latest Version (GraphQL spec) September 2025 edition (first since October 2021)
Latest Version (gRPC) gRPC core 1.84.0 (2026-09-11). Protobuf Edition 2024
Schema language JSON Schema 2020-12 (default dialect in OpenAPI 3.1+)
Error format standard RFC 9457 Problem Details (2023, obsoletes RFC 7807)
Auth baseline OAuth 2.0 + RFC 9700 Security BCP (2025). OAuth 2.1 still a draft (-16, 2026-09-03)
Security threat model OWASP API Security Top 10, 2023 edition (still the latest)
Transports HTTP/1.1, HTTP/2 (RFC 9113), HTTP/3 (RFC 9114) over QUIC (RFC 9000)
Governance OpenAPI Initiative and AsyncAPI Initiative (Linux Foundation), GraphQL Foundation, CNCF (gRPC incubating; Connect RPC sandbox; CloudEvents graduated), IETF, WHATWG, W3C
Licenses OpenAPI and AsyncAPI specs: Apache-2.0. gRPC: Apache-2.0. Apollo Router / Federation: Elastic License 2.0

Full version tables are in Reference — Specification and Standard Versions.

Architecture at a Glance

Where each paradigm usually sits in a production API platform:

flowchart LR
    CL["Browsers, mobile apps,<br/>partner backends"] --> EDGE["CDN + API gateway<br/>(Kong, Envoy, AWS API Gateway)"]
    EDGE -->|"REST + OpenAPI"| REST["Public REST API"]
    EDGE -->|"GraphQL"| GQL["GraphQL router<br/>(federated subgraphs)"]
    EDGE -->|"SSE / WebSocket"| RT["Real-time stream server"]
    REST -->|"gRPC / Connect"| SVC["Internal microservices"]
    GQL -->|"subgraph queries"| SVC
    SVC -->|"events (AsyncAPI)"| BUS["Kafka / NATS"]
    SVC -.->|"signed webhooks"| CL

API Generations

Era Dominant paradigm Transport Data format
1998–2008 SOAP / XML-RPC HTTP (POST only) XML
2008–2015 REST HTTP/1.1 (full verb set) JSON
2015–2020 REST + GraphQL + gRPC HTTP/1.1, HTTP/2 JSON, Protocol Buffers
2020–present Plus tRPC, SSE (LLM streaming), Connect RPC, WebTransport HTTP/2, HTTP/3, WebSocket JSON, Protobuf, binary streams

No single paradigm is universally best. The right choice depends on the consumer, team skills, and performance needs. The decision flowchart is in Explanation — Protocol Comparison Overview.

What Changed in 2025–2026

  • OpenAPI 3.2 (2025-09-19; patch 3.2.1 on 2026-09-10): streaming media types (itemSchema for SSE and JSON Lines), the query operation, additionalOperations, hierarchical tags, $self, and the OAuth 2.0 device flow. See Reference — OpenAPI 3.x Feature Matrix.
  • HTTP QUERY method (RFC 10008, June 2026): a safe, idempotent request with a body, the standard replacement for POST /search.
  • Deprecation header (RFC 9745, March 2025) standardizes the Deprecation field alongside Sunset (RFC 8594). See How-to Guides — API Versioning.
  • GraphQL September 2025 edition: OneOf input objects, schema coordinates. graphql-js 17 GA (2026-06-15). Apollo Server 4 reached end-of-life on 2026-01-26.
  • AsyncAPI 3.1.0 (2026-01-31), Arazzo 1.1.0 (2026-05-17), and Overlay 1.1.0 (2026-01-14) from the OpenAPI Initiative.
  • OAuth: RFC 9700 (Security BCP, January 2025) is the current baseline. OAuth 2.1 remains a draft.
  • Web PKI: Let's Encrypt ended OCSP (2025-08-06). TLS certificate lifetime is capped at 200 days from 2026-03-15, falling to 47 days in 2029.

Key Concepts at a Glance

Concept What it is Details
REST Resource-oriented architecture using HTTP methods Explanation
GraphQL Query language with typed schema, single endpoint Explanation
gRPC High-performance RPC using Protocol Buffers + HTTP/2 Explanation
SOAP XML-based protocol with strict contracts (WSDL) Explanation
WebSocket Full-duplex persistent connection Explanation
SSE Server-Sent Events, server-to-client streaming Explanation
Webhooks Event-driven HTTP callbacks Explanation
tRPC End-to-end type-safe TypeScript APIs Explanation
OpenAPI / AsyncAPI API description standards How-to Guides
API Gateway Central entry point for routing, auth, rate limiting How-to Guides
Rate Limiting Throttling request volume How-to Guides
API Versioning Managing breaking changes, Deprecation/Sunset headers How-to Guides
Authentication OAuth 2.x, PKCE, DPoP, API keys, JWT, mTLS How-to Guides
CORS Cross-Origin Resource Sharing How-to Guides
HATEOAS Hypermedia-driven REST discovery Explanation
Richardson Maturity REST maturity levels (0–3) Explanation
API-First Design Design the contract before implementation How-to Guides
Federation Composing multiple GraphQL services into one graph Explanation
Protocol Buffers Binary serialization and IDL for gRPC Explanation
HTTP/2 vs HTTP/3 Transport evolution (TCP vs QUIC) Explanation
BFF Pattern Backend-for-Frontend dedicated API layer Explanation
Persisted Queries APQ and trusted documents for GraphQL Explanation
Content Negotiation Format agreement via Accept headers Explanation
HTTP Methods and Status Codes Safety, idempotency, RFC 9110 names Reference
gRPC Status Codes 17 codes and their HTTP mapping Reference
OWASP API Top 10 Critical API security risks (2023) Explanation
BOLA / IDOR Broken Object Level Authorization Explanation
JWT Security Token attack vectors and defenses Explanation
Authorization Models RBAC, ABAC, ReBAC Explanation
Hardening Checklists SSRF deny-list, headers, TLS, gRPC Reference
API Security Testing Manual checklist and scanners How-to Guides
JSON Patch / Merge Patch PATCH body formats (RFC 6902 / RFC 7396) Explanation
GraphQL Error Handling Partial responses, extensions, masking Explanation
GraphQL Caching Normalized client cache, APQ, @cacheControl Explanation
gRPC-Web and Connect Browser bridge for gRPC Explanation
Schema Stitching Legacy GraphQL composition vs Federation Explanation
API Caching CDN, stale-while-revalidate, invalidation How-to Guides
Retry Patterns Exponential backoff, jitter, retry budgets How-to Guides
SDK Code Generation openapi-generator, graphql-codegen, buf generate How-to Guides
API Documentation Swagger UI, Redoc, Scalar, GraphiQL How-to Guides
API Governance Spectral linting, breaking-change detection in CI How-to Guides

Evaluation

Paradigm Maturity Strengths Weaknesses / fit
REST Mature, universal HTTP-native caching, massive tooling (OpenAPI), every client can call it Over/under-fetching; no standard for queries until QUERY (2026)
GraphQL Production-stable Client-shaped queries, typed schema, federation for multi-team graphs Harder caching and rate limiting; query-cost attacks; steeper backend learning curve
gRPC Production-stable, CNCF incubating Fast binary encoding, streaming, strict contracts, codegen Not browser-native (needs gRPC-Web or Connect); L4 load balancing pitfalls
SOAP Legacy, still alive in enterprise WSDL contracts, WS-Security Verbose XML, heavy tooling
WebSocket Mature Full-duplex, low overhead per message Stateful connections complicate scaling and auth
SSE Mature (WHATWG) Simple server push over HTTP, auto-reconnect; the de facto LLM streaming transport One direction only; EventSource is GET-only
WebTransport Emerging Multiplexed streams and datagrams over HTTP/3 IETF protocol still a draft; Safari support only since 26.4
tRPC Growing (v11) Zero-codegen end-to-end types TypeScript-only; tied to one team's monorepo
Webhooks Universal pattern Push instead of polling Delivery, ordering, and security need careful engineering

Topic Map

  • How-to Guides: describe, secure, version, test, document and operate web APIs.
  • Reference: spec and RFC versions, tooling versions, HTTP methods, status codes and headers, gRPC and WebSocket codes, OpenAPI matrix, security checklists.
  • Explanation: how REST, GraphQL, gRPC, SOAP, WebSocket, SSE, webhooks and tRPC work, their transports, and the API threat model.

Sources

Specifications and Standards

Design Guidelines

GraphQL and gRPC Ecosystem

Security

Operations and Tooling

Questions

  • When will OAuth 2.1 become an RFC? Still draft -16 (2026-09-03). Until then, cite RFC 9700 for the same guidance. Track the datatracker page; see How-to Guides — OAuth.
  • Will core gRPC adopt HTTP/3? gRFC G2 exists and grpc-dotnet implements it, but grpc-go, grpc-java, and gRPC core had no official HTTP/3 transport as of 2026-09. See Explanation — HTTP/3.
  • Will the GraphQL Foundation's Composite Schemas spec displace Apollo Federation 2? It is still at Stage 0 (Preliminary). Apache-2.0 routers (Cosmo, Hive Gateway) already implement the Apollo Federation protocol. See Explanation — Federation.
  • How fast will tooling adopt OpenAPI 3.2 and the QUERY method? Check generator, linter, gateway, and CDN support before depending on either. See Reference — OpenAPI 3.x Feature Matrix.
  • Will the IETF RateLimit and Idempotency-Key headers reach RFC status? Both were still Internet-Drafts in 2026-09. See Reference — HTTP Headers for APIs.
  • Is tRPC's TypeScript coupling a ceiling for adoption? Open. v11 moved subscriptions to SSE and added a TanStack-native client, but it remains TypeScript-only.
  • Benchmarks: is there a reproducible REST vs GraphQL vs gRPC benchmark with stated conditions? None is recorded here; Reference — Benchmarks now lists only structural differences.