This is the foundation. Every REST API diagram follows this same structure you just add more detail as the flow gets more complex.

Can you show a complete CRUD REST API flow in Mermaid?

Real APIs do more than just read data. Here's a sequence diagram that covers a typical create, read, update, and delete flow through a REST API:

sequenceDiagram
 participant Client
 participant API as API Gateway
 participant Service as User Service
 participant DB as PostgreSQL

 Note over Client,DB: CREATE - POST /api/users

 Client->>API: POST /api/users (JSON body)
 API->>Service: Validate & create user
 Service->>DB: INSERT INTO users
 DB-->>Service: User created (id: 42)
 Service-->>API: 201 Created
 API-->>Client: 201 Created { id: 42 }

 Note over Client,DB: READ - GET /api/users/42

 Client->>API: GET /api/users/42
 API->>Service: Fetch user by ID
 Service->>DB: SELECT FROM users WHERE id=42
 DB-->>Service: User record
 Service-->>API: User data
 API-->>Client: 200 OK { user object }

 Note over Client,DB: UPDATE - PUT /api/users/42

 Client->>API: PUT /api/users/42 (JSON body)
 API->>Service: Validate & update user
 Service->>DB: UPDATE users SET ...
 DB-->>Service: Rows affected: 1
 Service-->>API: User updated
 API-->>Client: 200 OK { updated user }

 Note over Client,DB: DELETE - DELETE /api/users/42

 Client->>API: DELETE /api/users/42
 API->>Service: Delete user
 Service->>DB: DELETE FROM users WHERE id=42
 DB-->>Service: Rows affected: 1
 Service-->>API: User deleted
 API-->>Client: 204 No Content

The Note over syntax adds labeled sections, which helps readers scan through longer diagrams without getting lost.

How do you handle authentication in a REST API sequence diagram?

Most production APIs require authentication. Showing the auth step makes the diagram much more realistic. Here's an example using JWT token-based authentication:

sequenceDiagram
 participant Client
 participant API
 participant Auth as Auth Service
 participant DB

 Client->>API: POST /api/auth/login { email, password }
 API->>Auth: Validate credentials
 Auth->>DB: SELECT user WHERE email = ...
 DB-->>Auth: User record + hashed password
 Auth->>Auth: Compare password hash
 Auth-->>API: Credentials valid
 API-->>Client: 200 OK { access_token, refresh_token }

 Note over Client,DB: Authenticated request

 Client->>API: GET /api/users/42 (Bearer token)
 API->>Auth: Verify JWT token
 Auth-->>API: Token valid (user_id: 42)
 API->>DB: SELECT FROM users WHERE id=42
 DB-->>API: User record
 API-->>Client: 200 OK { user object }

This shows two distinct phases: the login exchange and then a subsequent authenticated request. You can use fragments like alt and loop to show branching logic such as failed login attempts or token refresh cycles. We cover those patterns in more detail in our guide on alt and loop fragments in sequence diagrams.

How do you show error handling and conditional flows?

Not every API call succeeds. A good diagram shows what happens when things go wrong. Mermaid's alt fragment lets you draw two branches the happy path and the error path:

sequenceDiagram
 participant Client
 participant API
 participant DB

 Client->>API: GET /api/users/999

 alt User found
 API->>DB: SELECT FROM users WHERE id=999
 DB-->>API: User record
 API-->>Client: 200 OK { user }
 else User not found
 API->>DB: SELECT FROM users WHERE id=999
 DB-->>API: No results
 API-->>Client: 404 Not Found { error: "User not found" }
 end

You can nest alt blocks and combine them with opt (optional) or loop (repeating) fragments depending on how detailed you need the flow to be.

What common mistakes break Mermaid REST API diagrams?

Working with these diagrams regularly reveals a few recurring issues:

• Missing arrow types. Using ->> everywhere instead of -->> for responses makes the diagram hard to read. Solid arrows mean calls; dashed arrows mean returns.
• Too many participants on one diagram. Once you pass six or seven participants, the diagram gets wide and messy. Split it into multiple diagrams if needed.
• Forgetting the end keyword on fragments. Every alt, loop, or opt block must close with end. Omitting it gives you a syntax error with no helpful message.
• Writing vague message labels. "Do stuff" or "process request" tells the reader nothing. Be specific: "Validate JWT token" or "Insert order record."
• No status codes in responses. Including HTTP status codes (200, 201, 404, 500) in your response messages makes the diagram actually useful for debugging.