System Type: Web Service

Patterns, failure modes, and anti-patterns for request/response web services.

API Patterns

REST

When to use. Public APIs, browser-facing services, CRUD-heavy domains, when discoverability and cacheability matter. When to avoid. Highly relational data with many nested queries (N+1 fetches). Real-time bidirectional communication. High-throughput internal service-to-service calls where payload efficiency matters. Key decisions. Resource naming, versioning strategy (URL vs header), pagination approach, error format.

GraphQL

When to use. Multiple client types needing different data shapes from the same backend. Complex, nested data relationships. When frontend teams need to iterate independently from backend. When to avoid. Simple CRUD APIs. Server-to-server communication. When caching at the HTTP layer is important (GraphQL's POST-based model breaks HTTP caching). When the team doesn't have GraphQL operational expertise. Key decisions. Schema-first vs code-first, query complexity limits, N+1 resolution strategy (DataLoader pattern), authorization model.

gRPC

When to use. Internal service-to-service communication. When payload size and serialization speed matter. When you want strongly-typed contracts with code generation. Streaming use cases. When to avoid. Browser clients (requires grpc-web proxy). When human readability of requests matters for debugging. When the team lacks protobuf experience. Public APIs (tooling ecosystem is smaller). Key decisions. Proto file organization, backward compatibility discipline, deadline propagation, load balancing (L7 required for HTTP/2).

Scaling Patterns

Horizontal scaling. Add more instances behind a load balancer. Requires stateless services (or externalized state). The default approach for web services. Watch for: session affinity requirements, connection pool exhaustion at the database, cache consistency across instances.

Vertical scaling. Bigger machines. Simpler than horizontal but has a ceiling. Right for: databases, in-memory workloads, and when horizontal scaling's coordination cost exceeds the performance benefit.

Autoscaling. Scale instance count based on metrics (CPU, request rate, queue depth). Essential for variable load. Watch for: cold start latency, scaling lag, minimum instance counts for availability, cost runaway from misconfigured scaling policies.

CDN and edge caching. Serve static and cacheable dynamic content from edge locations. Dramatically reduces latency and origin load. Watch for: cache invalidation complexity, cache poisoning, TTL tuning, varying content by headers (accept-language, authorization).

Read replicas. Offload read traffic from the primary database. Watch for: replication lag causing stale reads, read-after-write consistency requirements, connection routing complexity.

Data Layer Patterns

RDBMS (PostgreSQL, MySQL). Default choice for structured, relational data. Strong consistency, ACID transactions, mature tooling. Scales vertically well; horizontal scaling requires sharding (hard) or read replicas (easier).

Document stores (MongoDB, DynamoDB). When data is naturally document-shaped, schema varies per record, or you need horizontal scaling without sharding complexity. Watch for: lack of joins, transaction limitations across documents, query patterns that don't match the data model.

Key-value stores (Redis, Memcached). Caching, session storage, rate limiting, leaderboards. Extremely fast for simple access patterns. Watch for: data loss on restart (unless configured for persistence), memory limits, using it as a primary datastore when it's a cache.

Search engines (Elasticsearch, OpenSearch). Full-text search, log aggregation, analytics on semi-structured data. Watch for: operational complexity, eventual consistency, write amplification, cluster sizing that's hard to change later.

Observability

…