REST API Flow Diagram — Gateway, Cache & Service

Q: How do I document my own API this way?

Write the systems as boxes and connect them: Client -> API Gateway -> User Service: GET /users. Chain hops on one line wherever the flow is linear.

Diagram source. Edit it live in the browser

title REST API Request Flow

type database Cache

Client -> API Gateway: GET /users/123
API Gateway -> API Gateway: validate JWT token
API Gateway -> Cache: check cache key
Cache -> API Gateway: cache miss
API Gateway -> User Service: GET /users/123
User Service -> API Gateway: user data
API Gateway -> Cache: store response (TTL 60s)
API Gateway -> Client: 200 OK + user data

What this diagram shows

Most of an API call happens before your service even hears about it. The gateway takes the request, checks the token, and tries the cache first. Your backend only gets involved on a miss. Handy to have drawn out the next time someone asks why one request was slow and the next one wasn't.

Running Kong, or plain Nginx? Same boxes, different names on them.

Step-by-step flow breakdown

Client sends the requestThe client calls GET /users/123 with a bearer token in the header.

Gateway validates the tokenBefore forwarding, the gateway checks the token signature, issuer, and expiry.

Cache lookupThe gateway checks Redis/Memcached for a cached response.

Cache miss, so forward to the serviceOn a miss, the request routes to the upstream microservice.

Response cachedThe gateway stores the fresh response with a TTL before returning it.

200 OK returnedThe client receives the payload and renders it.

When to use this flow diagram

API docs. Consumers see what actually sits between them and the data.
Latency arguments. Point at the hop instead of guessing.
Deciding where a cache belongs, and what TTL you can live with.
Onboarding, so nobody has to read the gateway config just to learn the path.

Common variations

Add a database

Extend the chain with User Service -> "Postgres": query user, and declare type database "Postgres" to get the cylinder.

Rate limiting

Add API Gateway -> API Gateway: check rate limit right after the token check. A self-arrow works fine for internal steps.

GraphQL variant

Swap GET /users/123 for POST /graphql. Everything else stays put.

Related flow diagram examples

Frequently asked questions

What does a REST API flow diagram show?

One request's path through the gateway, cache, and backend service. Who gets called, in what order, and where the response actually comes from.

How do I document my own API this way?

Write the systems as boxes and connect them: Client -> API Gateway -> User Service: GET /users. Chain hops on one line wherever the flow is linear.

Does this work for microservices?

Yes, it's the same idea with more boxes. The microservices order flow example is this at architecture scale.

REST API Request Flow