← Systems Analysis: APIs, Integrations and Data
Lesson
Sequence diagram: who calls whom, and in what order
Read and draw a sequence diagram for the “place and pay for an order” scenario: participants, synchronous and asynchronous messages, replies and alternative branches (alt).
How to read a sequence diagram
Who calls whom, and when
A sequence diagram (UML 2.5.1) shows one scenario over time. Participants stand in a row at the top, each with a lifeline (a vertical dashed line). Time flows top to bottom; messages are horizontal arrows between lifelines. A narrow rectangle on a lifeline (activation) means the participant is busy. Arrow types and fragments: see the table below.
A webhook is also a synchronous HTTP call, started by the provider: the arrow runs from the provider to us, our 200 reply goes back dashed. An event to the broker is asynchronous: send and don't wait; receivers read the broker themselves.
The scenario below: the app calls POST /orders. The order service asks the provider to create a payment and gets a link; only now can it return 201 with the link. The customer pays; only then does the provider send the webhook. Then the service publishes OrderPaid (OrderCancelled in the failure branch). Each step waits for the previous one, so the order is fixed.
For the analyst: every arrow between systems is an API endpoint or an event; check it against the integration register (lesson 1.3) and the contracts. An arrow missing from the register is a gap: clarify it with the team and add it to the register and contract. Participants are systems, as on a context diagram, not database tables. A provider's decline is a reply, not a failure: don't wrap it in a loop; draw a separate alt branch.
Arrows and fragments
| Element | Meaning |
|---|---|
| Solid line, filled arrowhead | Synchronous call: the sender waits for a reply |
| Solid line, open arrowhead | Asynchronous message: the sender does not wait |
| Dashed line | Reply to a call |
| alt | Mutually exclusive branches, each with a condition in brackets: [payment succeeded] / [payment declined] |
| opt | The steps run only if the condition is true |
| loop | Repeated steps |
| ref | Reference to another diagram |
How to draw the diagram
- 1Participants
Left to right, in the order they join the scenario
- 2Main scenario
Calls and events from top to bottom, as time flows
- 3Replies
Dashed, back to the caller
- 4Failures
An alt fragment with a condition on each branch
- 5Cross-check
Every arrow is a row in the integration register and a contract
Lesson notes
Who calls whom, and when
A sequence diagram (UML 2.5.1) shows one scenario over time. Participants stand in a row at the top, each with a lifeline (a vertical dashed line). Time flows top to bottom; messages are horizontal arrows between lifelines. A narrow rectangle on a lifeline (activation) means the participant is busy. Arrow types and fragments: see the table below.
A webhook is also a synchronous HTTP call, started by the provider: the arrow runs from the provider to us, our 200 reply goes back dashed. An event to the broker is asynchronous: send and don't wait; receivers read the broker themselves.
The scenario below: the app calls POST /orders. The order service asks the provider to create a payment and gets a link; only now can it return 201 with the link. The customer pays; only then does the provider send the webhook. Then the service publishes OrderPaid (OrderCancelled in the failure branch). Each step waits for the previous one, so the order is fixed.
For the analyst: every arrow between systems is an API endpoint or an event; check it against the integration register (lesson 1.3) and the contracts. An arrow missing from the register is a gap: clarify it with the team and add it to the register and contract. Participants are systems, as on a context diagram, not database tables. A provider's decline is a reply, not a failure: don't wrap it in a loop; draw a separate alt branch.