3.3 Example: API Request

  1. User sends request to API.

  2. API queries Database.

  3. Database returns result → API → User.

1. User Sends Request to API

To bring together what you’ve learned about sequence diagrams, let’s build a simple but realistic example: a user sends a request to an API. This is one of the most common patterns in software — a user does something (like clicking “Submit”), which triggers a chain of messages between systems.

✅ What This Example Shows

In this example: 1️⃣ The User sends a request to the Frontend (like a web page or mobile app). 2️⃣ The Frontend forwards that request to the API Server. 3️⃣ The API Server processes the request and checks the Database if needed. 4️⃣ The API Server returns a response to the Frontend. 5️⃣ The Frontend shows the result to the User.

✅ The Mermaid Code

Here’s how you’d write this sequence diagram in Mermaid:

```mermaid
sequenceDiagram
  actor User
  participant Frontend
  participant API
  participant Database

  User->>Frontend: Click Submit
  Frontend->>API: Send API Request
  API->>Database: Query Data
  Database-->>API: Return Data
  API-->>Frontend: Send Response
  Frontend-->>User: Show Result
```

✅ What’s Happening Here

  • Participants:

    • User is an actor (a human).

    • Frontend, API, and Database are participants (system parts).

  • Messages:

    • User->>Frontend — The user initiates an action.

    • Frontend->>API — The frontend calls the backend API.

    • API->>Database — The API queries the database.

    • Database-->>API — The database returns data (dashed arrow for response).

    • API-->>Frontend — The API replies to the frontend.

    • Frontend-->>User — The frontend shows the final result to the user.

✅ What This Diagram Communicates

  • Who starts the interaction: The user.

  • What path the request follows: From the frontend to the API to the database — and back.

  • How responses travel: Dashed arrows show the flow of data back to the user.

  • The whole diagram reads top to bottom, like a timeline.

✅ Where to Use This

Use a diagram like this to:

  • Explain your app’s request flow to teammates.

  • Document an API call in your project wiki.

  • Show clients or non-technical stakeholders how your system handles user input.

In short:

📌 A simple sequence diagram makes it easy to show how a user’s action travels through your system, step by step — crystal clear for developers, testers, and non-tech readers alike.

2. API Queries Database

In many modern applications, when a user makes a request through an API — like logging in, fetching their profile, or getting product details — the API usually needs to fetch or update data in a database. This step is a key part of any sequence diagram for backend systems.

✅ Why Does the API Query the Database?

The API Server is the middle layer that:

  • Receives the request from the frontend or client.

  • Validates or processes the request.

  • Queries the Database to read or write data.

  • Packages the response and sends it back up the chain.

In your sequence diagram, showing this step makes it clear where data is stored and which component owns it.

✅ Mermaid Syntax: API and Database

In Mermaid, this interaction is just another message arrow — it shows:

  • The API calls the Database.

  • The Database returns a result.

Example snippet:

  • ->> means the API requests data.

  • -->> means the Database returns data.

✅ Putting It in Context

Here’s how the full diagram looks with the API-Database step included:

✅ What Happens in This Step

  • When the Frontend sends the user’s request, the API might need more information than it has on hand.

  • The API sends a query to the Database — for example, “Is this username valid?” or “Fetch all items in this category.”

  • The Database checks its records and returns the matching data.

  • The API uses this data to build a final response for the user.

✅ Why It’s Important to Show

This step:

  • Makes it clear that the API does not store data itself — it delegates that to the Database.

  • Shows where the data comes from when building a response.

  • Helps developers and architects see possible points of failure, like slow queries or missing data.

  • Is useful for debugging and performance tuning — you know exactly when and where the Database is involved.

✅ Tips for Real-World Diagrams

✔️ Use clear, simple labels like Query Data, Fetch Record, or Write Data to describe what the API is doing. ✔️ If you have multiple database calls, show each one in order — it’s fine to have multiple arrows back and forth. ✔️ Combine with notes to explain what kind of data is being read or written if needed.

In short:

📌 The API → Database step is the backbone of how modern apps work — your sequence diagram shows exactly when the data is requested, how it flows, and who handles it before it’s returned to the user.

3. Database Returns Result → API → User

After the API Server queries the Database, the final part of the interaction is to return the data back through the chain — from the Database to the API, then to the Frontend, and finally back to the User.

This step completes the request-response cycle and shows exactly how information flows back to the person or system that asked for it.

✅ Why Is This Step Important?

When you diagram this return path, you:

  • Make it clear which system is responsible for processing the result.

  • Show how raw database data is handled or formatted by the API before reaching the user.

  • Highlight where you can add things like error handling, validation, or caching.

Without this final return flow, the diagram would be incomplete — the whole point is to show the round trip of the request and response.

✅ Mermaid Syntax: Returning the Result

Here’s the key part in Mermaid syntax:

  • -->> uses a dashed arrow to show the response path.

  • The Database sends data to the API.

  • The API processes it and forwards it to the Frontend.

  • The Frontend displays it for the User.

✅ Full Example in Context

Here’s the complete code block again for clarity:

✅ How This Final Step Works

1️⃣ Database responds to the API with the requested data — for example, a user profile or a product list. 2️⃣ The API might transform this data (e.g., filter fields, add status codes, or wrap it in JSON). 3️⃣ The API sends the response to the Frontend. 4️⃣ The Frontend takes that response and renders it for the User — showing a success message, updating the page, or displaying an error if something went wrong.

✅ Key Takeaways

✔️ The Database only stores and returns data — it doesn’t talk to the User directly. ✔️ The API acts as the middle layer that knows how to talk to the Database and how to reply to the Frontend. ✔️ The Frontend makes sure the User gets a clear, usable result.

✅ Why It Matters in a Sequence Diagram

  • It shows the entire lifecycle of a request.

  • It highlights dependencies — for example, if the Database is slow, the User’s wait time increases.

  • It documents exactly where responses flow, which is helpful for troubleshooting, design discussions, and explaining the system to others.

In short:

📌 Database → API → Frontend → User ties your whole interaction together — your sequence diagram clearly shows how data travels back to the person who started the request.

Previous3.2 Sequence Diagram SyntaxNextChapter 4

Last updated