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 |
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 |
Sources¶
REST¶
- REST API Tutorial
- REST Architectural Constraints — restfulapi.net
- Richardson Maturity Model — Martin Fowler
- HTTP Semantics — RFC 9110
- JSON:API Specification
- OpenAPI Specification
- Microsoft REST API Guidelines
- Google API Design Guide
- Zalando RESTful API Guidelines
GraphQL¶
- GraphQL Official Documentation
- GraphQL Specification
- Apollo GraphQL Documentation
- Apollo Federation Documentation
- GraphQL Best Practices — graphql.org
- Relay Specification
gRPC¶
Other Paradigms¶
- WebSocket API — MDN
- Server-Sent Events — MDN
- tRPC Documentation
- SOAP Web Services Tutorial — W3Schools
API Design & Security¶
- OWASP API Security Top 10 (2023)
- OAuth 2.0 — RFC 6749
- JSON Web Tokens — RFC 7519
- API Design Patterns — JJ Geewax (Manning)
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?