API request lifecycle
Client, gateway, service, database, and back.
Every slow API starts as a mystery: is it the database, the network, the code? This template shows where the time actually goes — the request bounces from client to gateway to service, the service checks the cache, misses, hits the database, updates the cache, and sends the response back through the same path. Each hop is a potential latency hotspot.
The sequence view makes asynchrony and caching explicit: notice the cache miss (no data returned) triggering a database query, then the cache update. This is the pattern behind almost every fast API. Dashed arrows mark responses and show the request flowing back up the stack.
When to use this template
- API performance debugging — annotate each message with latency numbers (cache 1ms, database 50ms, network 10ms) to spot the bottleneck.
- Explaining API architecture to non-engineers — the vertical lifelines and message arrows make the flow clearer than prose or a static diagram.
- Cache strategy design — use this diagram to decide what to cache (slow queries), how to invalidate (subscribe to writes), and when to bypass (for fresh data endpoints).
How to adapt it
Rename participants to your real systems — Fastly instead of API Gateway, PostgreSQL instead of Database, DynamoDB instead of Cache — and layer in your infrastructure:
- Add authentication and rate-limiting as the first steps in the Gateway participant to show where identity and quota checks happen.
- Insert service-to-service calls if your API delegates to a second microservice instead of querying the database directly.
- Add background logging or analytics as an optional async message after the response to show observability infrastructure.
Visual edits regenerate clean code, so you can sketch service dependencies and cache layers without writing sequence syntax directly.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor Client
participant Gateway as API Gateway
participant Service
participant DB as Database
participant Cache as Cache
Client->>Gateway: HTTP POST /users
Gateway->>Service: Forward request
Service->>Cache: Check user exists
Cache-->>Service: Cache miss
Service->>DB: Query user
DB-->>Service: User data
Service->>Cache: Update cache
Service->>Service: Validate & transform
Service-->>Gateway: 200 OK + JSON
Gateway-->>Client: Response
Frequently asked questions
- What does an API request lifecycle diagram show?
- It traces a single HTTP request from client through every hop — gateway, service, database, cache — showing which systems communicate, in what order, and where network calls happen. It makes visible the latency budget (how many hops slow down the request) and the cache hit/miss paths that determine how fast your API feels to users.
- Why is the cache shown as a separate node instead of inside the service?
- Because the cache is often external (Redis, Memcached) and can fail independently. Drawing it as a participant makes the cache-miss path explicit — showing what happens when the cache does not have the data — and helps teams reason about cache consistency and invalidation.
- What is the difference between a cache hit and a database query?
- A cache hit is a memory lookup that takes microseconds; a database query is a network call that takes milliseconds. One cache miss that forces a database query can slow your API by 50–100x. This diagram makes that gap visible, so teams prioritize which frequently-accessed data to cache.
- How do I add error handling and timeouts to this diagram?
- Add optional response messages (use `-->>` instead of `->>`) for error cases: 'DB timeout' causing the service to return 503, or 'Cache unavailable' causing a direct DB query. Wrap critical paths in alt/else blocks showing happy-path vs. degraded-mode responses. Visual edits regenerate clean Mermaid code.