API gateway request routing
Gateway routing requests to microservices based on path and headers.
An API gateway is the single entry point for client requests in a microservices architecture. Every request flows through the same validation and routing logic, making it the place to enforce authentication, rate limiting, and request transformation. This sequence diagram shows the happy path: a client calls the gateway with a bearer token, the gateway validates it, routes to the correct backend based on the path, and returns the response.
The routing rules box at the bottom is where the intelligence lives — it's where you document which paths go to which services. In production, this lives in a config file, a service registry, or inline code; the diagram is the visual reference so everyone knows the rules without reading the source.
When to use this template
- Architecture documentation — show new engineers how requests flow through your gateway and which service owns which endpoint, eliminating the guess-and-ask spiral when onboarding.
- API contract reviews — add this diagram to your API documentation so consumers know the gateway they're talking to, what authentication it expects, and which headers it forwards or requires.
- Incident postmortems — when a routing misconfiguration sends traffic to the wrong service, annotate this diagram with the actual rules that were in place to show what went wrong.
How to adapt it
Start by renaming the backend services to your real microservices, then extend the routing:
- Add multiple request types — show different paths (GET /api/users/:id, POST /api/orders) routing to different services.
- Insert a rate limiter participant between the gateway and the auth service to document per-user or per-IP quotas.
- Add a cache check before routing to show where you avoid calling the backend entirely for frequently-requested data.
Visual edits regenerate clean Mermaid code, so you can build these variations and drop the diagram directly into your runbooks or architecture docs.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant C as Client
participant G as API Gateway
participant A as Auth Service
participant U as User Service
participant O as Order Service
C->>G: POST /api/orders (Bearer token)
G->>A: Validate token
A-->>G: Token valid (user_id: 42)
G->>O: POST /api/orders (forward)
O-->>G: 201 Created {order_id}
G-->>C: 201 Created
rect rgb(200, 150, 255)
Note over G: Routing rules:<br/>POST /api/orders → Order Service<br/>GET /api/users/* → User Service
end
Frequently asked questions
- What does an API gateway routing diagram show?
- It shows how an API gateway receives a client request, validates authentication, inspects the path and method, routes to the correct backend service, and returns the response. The routing rules rectangle makes the decision logic explicit, so every team member knows which service handles which endpoint without reading code.
- Should the gateway validate tokens or delegate to a separate auth service?
- Both patterns work; this diagram shows delegation to a separate auth service for clarity and reusability — the same validation logic works for every backend. Alternatively, the gateway can validate tokens directly using cached public keys. Which you choose depends on your security model and latency budget.
- What happens if a service is down?
- The gateway should have circuit-breaker or health-check logic (not shown here for clarity) to detect when a backend is unhealthy and either fail fast with a 503, try a failover instance, or queue the request for retry. Your team should add a note or a separate diagram documenting your failover strategy.
- How do I adapt this for rate limiting or caching?
- Add a participant for your rate limiter or cache before the routing decision — the gateway checks the cache first, and if it's a cache miss, it checks rate limits before forwarding to the backend. Visual edits regenerate clean Mermaid code, so you can sketch these extensions and export the diagram to your architecture docs.