Example: save an order and return confirmation
This interaction follows one request from the client to storage and back. The API returns confirmation after the database acknowledges the insert. It does not claim that payment, shipping or an entire order lifecycle has completed.
Example prompt
Create a sequence diagram with Client, Orders API and Database as participants. The Client sends POST /orders to the Orders API. The API inserts the order in the Database. The Database returns an order ID. The API returns 201 Created with that ID to the Client. Show this successful path only. Do not add a payment provider.
When a sequence diagram is the right choice
Choose a sequence diagram when timing and responsibility matter. It is useful for an API request, an authentication exchange, a message delivery workflow or a support interaction. It answers who sends each message and what happens before the next message.
A sequence diagram is a view of a scenario. It does not need to contain every component in your architecture. Start with the participants that take part in this particular interaction, then add detail only when it changes the explanation.
Plan participants, messages and alternatives
Before drawing, write down the starting event and the result the caller expects. Then trace the messages that connect them.
- Name participants by role or service, such as Browser, API and Database.
- Use message labels that describe the operation or event, rather than a vague “request.”
- Keep the time order readable from top to bottom.
- Distinguish a queued event from a response the caller waits for.
- Show a separate alternative for a rejected request, timeout or other meaningful failure.
Review the API contract in the diagram
In the order example, check whether the API really waits for the database write before returning 201 Created. If the implementation accepts work asynchronously, the status and response may be different. The diagram should reflect the contract you actually provide.
For authentication, separate the browser, your application and the identity provider. Do not combine a redirect, token exchange and session creation into one unlabeled arrow if the review depends on their order.
Keep architecture and execution separate
An architecture diagram shows that an API uses a database. A sequence diagram shows when that database is called during one interaction. They complement each other, but combining both views can hide the detail you are trying to explain.
Give the diagram a scenario-based title, such as Create an order: successful request. When a failure path needs several messages, give it a separate view rather than squeezing it into the margin.
Common questions
- Is a sequence diagram the same as a flowchart?
- No. A flowchart follows process steps and decisions. A sequence diagram follows messages between participants over time. Use the view that answers your audience’s question.
- What should an API sequence diagram include?
- Include the caller, the services involved in the scenario, labeled operations, important responses and any failure path that affects the API contract.
- Can I start with a text description?
- Yes. Describe the participants and message order explicitly. Nensea’s AI diagram generation creates an editable draft; early access is available through the homepage.
Put your next diagram in context.
Tell us what your team, class or lab needs to explain. Join the early access list to explore Nensea’s editable AI diagrams.
Get early access to Nensea