Web Services & APIs¶

A comprehensive reference covering web service API paradigms — REST, GraphQL, gRPC, SOAP, WebSocket, SSE, webhooks, and tRPC — from architectural principles and protocol internals to design patterns, security, versioning, and production operations.

Summary¶

Web services are software systems that expose functionality over a network using standardized protocols. APIs (Application Programming Interfaces) define the contract between client and server — what you can request, how to request it, and what you get back.

The API landscape has evolved through several generations:

Era	Dominant Paradigm	Transport	Data Format
1998–2008	SOAP / XML-RPC	HTTP (POST only)	XML
2008–2015	REST	HTTP (full verb set)	JSON
2015–present	REST + GraphQL + gRPC	HTTP/1.1, HTTP/2	JSON, Protocol Buffers
2020–present	tRPC, WebSocket, SSE added	HTTP, WS	JSON, Binary

No single paradigm is universally best — the right choice depends on use case, team expertise, client requirements, and performance needs.

Key Concepts at a Glance¶

Concept	What It Is	Details
REST	Resource-oriented architecture using HTTP verbs	architecture#rest-representational-state-transfer
GraphQL	Query language with typed schema, single endpoint	architecture#graphql
gRPC	High-performance RPC using Protocol Buffers + HTTP/2	architecture#grpc
SOAP	XML-based protocol with strict contracts (WSDL)	architecture#soap
WebSocket	Full-duplex persistent connection	architecture#websocket
SSE	Server-Sent Events — server-to-client streaming	architecture#server-sent-events-sse
Webhooks	Event-driven HTTP callbacks	architecture#webhooks
tRPC	End-to-end type-safe TypeScript APIs	architecture#trpc
OpenAPI / Swagger	REST API specification standard	operations#api-specification-formats
API Gateway	Central entry point for routing, auth, rate limiting	operations#api-gateways
Rate Limiting	Throttling request volume	operations#rate-limiting
API Versioning	Managing breaking changes	operations#api-versioning
Authentication	OAuth 2.0, API keys, JWT, mTLS	operations#authentication-and-authorization
CORS	Cross-Origin Resource Sharing	operations#cors-cross-origin-resource-sharing
HATEOAS	Hypermedia-driven REST discovery	architecture#hateoas
Richardson Maturity	REST maturity levels (0–3)	architecture#richardson-maturity-model
API-First Design	Design the API contract before implementation	operations#api-first-design
Federation	Composing multiple GraphQL services into one graph	architecture#federation
Protocol Buffers	Binary serialization format for gRPC	architecture#protocol-buffers
HTTP/2 vs HTTP/3	Transport protocol evolution (TCP vs QUIC)	architecture#http2-and-http3-quic
BFF Pattern	Backend-for-Frontend dedicated API layer	architecture#backend-for-frontend-bff
Persisted Queries	Pre-registered GraphQL queries for security/perf	architecture#graphql-persisted-queries
Content Negotiation	Client-server format agreement via Accept headers	architecture#content-negotiation
OWASP API Top 10	Critical API security vulnerabilities (2023)	security#owasp-api-security-top-10-2023
BOLA / IDOR	Broken Object Level Authorization attacks	security#api12023-broken-object-level-authorization-bola
JWT Security	Token attack vectors and defenses	security#jwt-attack-vectors
Authorization Models	RBAC, ABAC, ReBAC patterns	security#authorization-patterns
API Security Testing	Automated scanning and manual testing checklists	security#api-security-testing
JSON Patch / Merge Patch	PATCH body format standards (RFC 6902/7396)	architecture#patch-semantics-json-patch-vs-json-merge-patch
GraphQL Error Handling	Partial responses, error extensions, error masking	architecture#error-handling
GraphQL Caching	Normalized client cache, APQ, @cacheControl	architecture#caching
gRPC-Web	Browser bridge for gRPC via Envoy/Connect	architecture#grpc-web-browser-bridge
Schema Stitching	Legacy GraphQL composition vs Federation	architecture#federation-vs-schema-stitching
API Caching	CDN, stale-while-revalidate, invalidation patterns	operations#api-caching-strategies
Retry Patterns	Exponential backoff, jitter, retry budgets	operations#retry-patterns
SDK Code Generation	openapi-generator, graphql-codegen, buf generate	operations#sdk-and-client-code-generation
API Documentation	Swagger UI, Redoc, Scalar, GraphiQL	operations#api-documentation-generation
API Governance	Spectral linting, breaking change detection in CI	operations#api-governance-and-linting

Evaluation¶

Dimension	Rating	Notes
REST	Mature, universal	De facto standard; massive tooling ecosystem; HTTP-native
GraphQL	Strong for complex frontends	Eliminates over/under-fetching; steep learning curve for backend
gRPC	Best for service-to-service	Fastest protocol; not browser-native without proxy
SOAP	Legacy but alive in enterprise	Strong typing, WS-Security; verbose and complex
WebSocket	Essential for real-time	Full-duplex; connection management complexity
SSE	Standard for LLM streaming	Auto-reconnect, HTTP-native, simpler than WebSocket
tRPC	Best for TypeScript monorepos	Zero codegen, maximum DX; locked to TS ecosystem
Webhooks	Essential for event-driven	Universal pattern; reliability requires careful engineering

Sources¶

REST¶

GraphQL¶

gRPC¶

Other Paradigms¶

API Design & Security¶

HTTP Transport¶

Operations & Tooling¶

Questions¶

How will HTTP/3 (QUIC) change the API transport landscape — will gRPC adopt it?
Will GraphQL Federation v2 become the standard for microservice API composition, or will alternatives like GraphQL Mesh gain traction?
Is tRPC's tight TypeScript coupling a strength or a ceiling for broader adoption?
How will AI-generated API clients (from OpenAPI specs) change the developer experience for REST?