Web Services & APIs¶
A reference for web service API paradigms — REST, GraphQL, gRPC, SOAP, WebSocket, SSE, webhooks, and tRPC. It covers architectural principles, protocol internals, 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 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 | apis/web-services/architecture#rest-representational-state-transfer |
| GraphQL | Query language with typed schema, single endpoint | apis/web-services/architecture#graphql |
| gRPC | High-performance RPC using Protocol Buffers + HTTP/2 | apis/web-services/architecture#grpc |
| SOAP | XML-based protocol with strict contracts (WSDL) | apis/web-services/architecture#soap |
| WebSocket | Full-duplex persistent connection | apis/web-services/architecture#websocket |
| SSE | Server-Sent Events — server-to-client streaming | apis/web-services/architecture#server-sent-events-sse |
| Webhooks | Event-driven HTTP callbacks | apis/web-services/architecture#webhooks |
| tRPC | End-to-end type-safe TypeScript APIs | apis/web-services/architecture#trpc |
| OpenAPI / Swagger | REST API specification standard | apis/web-services/operations#api-specification-formats |
| API Gateway | Central entry point for routing, auth, rate limiting | apis/web-services/operations#api-gateways |
| Rate Limiting | Throttling request volume | apis/web-services/operations#rate-limiting |
| API Versioning | Managing breaking changes | apis/web-services/operations#api-versioning |
| Authentication | OAuth 2.0, API keys, JWT, mTLS | apis/web-services/operations#authentication-and-authorization |
| CORS | Cross-Origin Resource Sharing | apis/web-services/operations#cors-cross-origin-resource-sharing |
| HATEOAS | Hypermedia-driven REST discovery | apis/web-services/architecture#hateoas |
| Richardson Maturity | REST maturity levels (0–3) | apis/web-services/architecture#richardson-maturity-model |
| API-First Design | Design the API contract before implementation | apis/web-services/operations#api-first-design |
| Federation | Composing multiple GraphQL services into one graph | apis/web-services/architecture#federation |
| Protocol Buffers | Binary serialization format for gRPC | apis/web-services/architecture#protocol-buffers |
| HTTP/2 vs HTTP/3 | Transport protocol evolution (TCP vs QUIC) | apis/web-services/architecture#http2-and-http3-quic |
| BFF Pattern | Backend-for-Frontend dedicated API layer | apis/web-services/architecture#backend-for-frontend-bff |
| Persisted Queries | Pre-registered GraphQL queries for security/perf | apis/web-services/architecture#graphql-persisted-queries |
| Content Negotiation | Client-server format agreement via Accept headers | apis/web-services/architecture#content-negotiation |
| OWASP API Top 10 | Critical API security vulnerabilities (2023) | apis/web-services/security#owasp-api-security-top-10-2023 |
| BOLA / IDOR | Broken Object Level Authorization attacks | apis/web-services/security#api12023-broken-object-level-authorization-bola |
| JWT Security | Token attack vectors and defenses | apis/web-services/security#jwt-attack-vectors |
| Authorization Models | RBAC, ABAC, ReBAC patterns | apis/web-services/security#authorization-patterns |
| API Security Testing | Automated scanning and manual testing checklists | apis/web-services/security#api-security-testing |
| JSON Patch / Merge Patch | PATCH body format standards (RFC 6902/7396) | apis/web-services/architecture#patch-semantics-json-patch-vs-json-merge-patch |
| GraphQL Error Handling | Partial responses, error extensions, error masking | apis/web-services/architecture#error-handling |
| GraphQL Caching | Normalized client cache, APQ, @cacheControl | apis/web-services/architecture#caching |
| gRPC-Web | Browser bridge for gRPC via Envoy/Connect | apis/web-services/architecture#grpc-web-browser-bridge |
| Schema Stitching | Legacy GraphQL composition vs Federation | apis/web-services/architecture#federation-vs-schema-stitching |
| API Caching | CDN, stale-while-revalidate, invalidation patterns | apis/web-services/operations#api-caching-strategies |
| Retry Patterns | Exponential backoff, jitter, retry budgets | apis/web-services/operations#retry-patterns |
| SDK Code Generation | openapi-generator, graphql-codegen, buf generate | apis/web-services/operations#sdk-and-client-code-generation |
| API Documentation | Swagger UI, Redoc, Scalar, GraphiQL | apis/web-services/operations#api-documentation-generation |
| API Governance | Spectral linting, breaking change detection in CI | apis/web-services/operations#api-governance-and-linting |
Evaluation¶
| Dimension | Rating | Notes |
|---|---|---|
| REST | Mature, universal | The standard, with a massive tooling ecosystem and HTTP-native design |
| GraphQL | Strong for complex frontends | Eliminates over/under-fetching, steep learning curve for the backend |
| gRPC | Best for service-to-service | Fastest protocol, not browser-native without a proxy |
| SOAP | Legacy but alive in enterprise | Strong typing and 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 the TS ecosystem |
| Webhooks | Essential for event-driven | Universal pattern, reliability requires careful engineering |
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)
- OWASP REST Security Cheat Sheet
- OWASP GraphQL Cheat Sheet
- OWASP gRPC Security Cheat Sheet
- OWASP JWT for Java Cheat Sheet
- OWASP SSRF Prevention Cheat Sheet
- OAuth 2.0 — RFC 6749
- OAuth 2.1 Draft
- PKCE — RFC 7636
- JSON Web Tokens — RFC 7519
- API Design Patterns — JJ Geewax (Manning)
- Google Zanzibar Paper
HTTP Transport¶
Operations & Tooling¶
- OpenAPI 3.1.0 Specification
- AsyncAPI 3.0 Documentation
- CloudEvents Specification
- Prism Mock Server — Stoplight
- k6 Load Testing
- OpenTelemetry Documentation
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?