What fails immediately
Timeouts, 5xxs, or throttling errors surface in the active request path.
API vs Message vs Event-Driven Architecture
Decision patterns for synchronous APIs, queues, and event streams
10 min read
API-Driven Architecture
Synchronous contracts for request/response workflows
Mental Model
Think of this as a phone call between systems: a client asks for work now and waits for a response now. Contracts are explicit, usually versioned, and behavior is tightly tied to endpoint semantics.
Decoupling Reality
API style has low temporal decoupling because callers wait in-line. It can offer deployment decoupling with stable contracts, but semantic coupling stays high because consumers depend on endpoint meaning and behavior.
Failure Shape
Fast, loud, and potentially cascading. API failures are visible to users immediately; their virtue is clarity, not resilience.
What fails later
Retry storms, cache stampedes, and exhausted pools appear after initial slowdown.
What fails silently
Latency creep and hidden N+1 fan-out can degrade UX before hard failures trigger alerts.
Core Components
Client
Web app, mobile app, or backend calling an API endpoint over HTTP/gRPC.
API Gateway
Entry point that handles routing, auth enforcement, throttling, and often request shaping.
Service
Business logic layer that validates input, orchestrates calls, and executes rules.
Database
System of record for writes and reads, often split into OLTP + read models.
Auth
Identity and authorization checks using tokens, policies, and scopes.
Load Balancer
Distributes incoming traffic across service instances for availability.
Cache
Reduces repeated reads and protects downstream dependencies.
Best At
- Low-latency user interactions that need immediate feedback
- Clear authority boundaries where one service must say yes or no immediately
- Simple business flows with strict request/response semantics
- Strong API contracts and straightforward governance
- Use cases where clients need explicit error codes and retries
Pros
- Clear contracts and discoverable interfaces
- Good for synchronous UX flows
- Mature tooling for auth, rate limiting, and API lifecycle
- Easy to reason about call chains in small to medium systems
Cons
- Tight runtime coupling between caller and callee
- Cascading failures when dependencies are slow/unavailable
- Chatty APIs can explode latency and infrastructure cost
- Version sprawl can accumulate long-term maintenance debt
Gotchas
- N+1 calls across microservices can quietly dominate latency
- Thundering herd on cache misses can overload databases
- Unbounded pagination leads to memory and timeout problems
- Retries without idempotency can duplicate side effects
- Overly granular endpoints create chatty client behavior
Architectural smell
Every new feature requires coordinated endpoint changes across many services before you can ship.
When to Use
You need strict request/response with immediate user confirmation
Example: User profile reads/writes and account settings APIs
Consumers require explicit contracts with auth and validation boundaries
Example: Public partner API with versioned endpoints
Workflow complexity is modest and end-to-end latency is key
Example: Search suggestions, cart updates, pricing lookups
Don't use this when...
Do not use as the primary workflow model when a business process spans many services with partial success and long-running compensations.
Scaling Playbook
Naive
Team context: Small team with shared context and direct communication.
- Single service instance behind load balancer
- Add basic pagination and per-client rate limiting
- Introduce cache for read-heavy endpoints
Intermediate
Team context: Multiple teams with partial ownership and explicit service boundaries.
- Horizontal scale stateless API instances
- Use read replicas and cache invalidation strategy
- Add API gateway throttling and token bucket policies
- Implement circuit breakers and bulkheads for dependency isolation
Advanced
Team context: Independent roadmaps, formal SLOs, and dedicated on-call rotation.
- Adopt BFF patterns per client experience
- Offload long-running steps to async pipelines
- Use streaming/pagination contracts to cap payload size
- Add adaptive rate limits, workload shedding, and SLO-aware routing
Typical Stack
API layer
- REST or gRPC services
- API gateway
- OpenAPI contracts
Caching and data
- Redis or in-memory cache
- SQL/NoSQL primary store
- Read replicas
Cloud examples
- AWS: API Gateway + ALB + ECS/EKS + RDS/ElastiCache
- GCP: API Gateway/Apigee + GKE + Cloud SQL + Memorystore
- Azure: API Management + AKS/App Service + Azure SQL + Redis
Interactive Diagram
Click a node to inspect behavior, failure modes, and scaling considerations.
Observability + Reliability
Observability burden: Moderate burden: request traces are linear, but dependency fan-out and retries still require disciplined instrumentation.
Metrics to Watch
- P50/P95/P99 latency per endpoint
- Error rate by status code and dependency
- Rate-limit hits, cache hit ratio, request volume
- Saturation indicators: CPU, DB connections, queue depth for async offloads
Logging / Tracing
- Structured request logs with trace/span IDs
- Trace gateway -> service -> datastore hops
- Capture route, auth scope, and upstream dependency timings
Failure Handling
- Timeout budgets per hop and client retry policies
- Circuit breakers, bulkheads, and fallback responses
- Idempotency keys for mutating endpoints
Scenario Picker
Scenario Guidance
Recommended architecture(s): API-Driven Architecture
Reasoning
Profile reads and writes usually need immediate request/response confirmation and clear auth boundaries.
Watch out for
- N+1 calls when profile aggregates many sub-services
- Version sprawl across mobile/web clients
Scaling notes
- Read-through cache
- Pagination for activity/history endpoints
- BFF for client-specific payloads