title REST API Request/Response
participant "Mobile App" as App
participant "API Gateway" as GW
participant "User Service" as US
participant Cache
App->GW: GET /users/123
GW->GW: Validate JWT token
GW->Cache: Check cache key
Cache-->GW: Cache miss
GW->US: GET /users/123
US-->GW: {id:123, name:"Alice"}
GW->Cache: SET cache (TTL 60s)
GW-->App: 200 OK + user data
What this diagram shows
This sequence diagram models a standard REST API request lifecycle through a production API Gateway stack. It illustrates four common concerns in a single flow: authentication (JWT validation), performance (cache layer), routing (gateway-to-microservice), and response handling.
This pattern appears in virtually every cloud-native backend — whether built on AWS API Gateway, Kong, Nginx, or a custom Go/Node proxy. Understanding the sequence helps teams debug latency issues, design cache invalidation strategies, and write accurate API documentation.
Step-by-step flow breakdown
GET /users/123 with a Bearer JWT token in the Authorization header.When to use a REST API sequence diagram
- API documentation — show the full request path so consumers know exactly what systems are involved
- Latency debugging — visualise where time is spent: gateway auth, cache lookups, or DB queries
- Cache design — map out where to introduce caching and what TTLs are appropriate
- Onboarding — new engineers can see the full call chain without reading gateway config files
- Incident review — reconstruct the sequence of calls during an outage
Common variations
Add a cache hit branch
Use an alt fragment to show two paths: [cache hit] returning immediately and [cache miss] routing to the service. This makes cache strategy explicit in the diagram.
Rate limiting
Add a step between JWT validation and the cache check where the gateway increments a rate-limit counter. Add an alt branch for [429 Too Many Requests].
Database-backed services
Extend the User Service box to show US->DB: SELECT user and DB-->US: row to document the full database interaction.
GraphQL variant
Replace the REST GET /users/123 with a POST /graphql with a query body. The gateway and service pattern remains identical.
Related sequence diagram examples
Frequently asked questions
What does a REST API sequence diagram show?
It shows the time-ordered messages between client, API gateway, cache, and backend services during a single API request cycle — making the call chain and dependencies explicit.
How do I document a REST API with a sequence diagram?
List your participants (client, gateway, service, database), then write the HTTP messages between them using arrow notation — A->B: GET /resource for requests, B-->A: 200 OK for responses. Open this example and adapt it to your own endpoints.
Can I use this REST API diagram template for free?
Yes — click Open in Editor to load it into SeqDiagram.com. Modify, export as PNG/SVG/Mermaid, or share with a link. Free, no account required.
Does this diagram work with Mermaid or PlantUML?
SeqDiagram.com exports to Mermaid with one click — compatible with GitHub READMEs, GitLab wikis, Notion, and Obsidian. You can also paste in existing Mermaid diagrams to edit them here.