What is the appropriate way to model API requests in Sequence Diagrams?

Question

I am about to create a few sequence diagrams to model the interactions in a web API.

There is a repeating pattern of request/response calls that I am not sure how to model.

Say, I have an API call to request attributes from an API endpoint. Would it be appropriate to use the standard reply pattern like this? Is it good style to assign use multiple return value variables (encrypted_attributes, hashes)?

Standard Reply Pattern

Or should custom requests/responses be created like this, reflecting that both request_attributest and return_encrypted_attributes are done by units independent from each other?

Custom Request/Repsonse Pattern

robalem · Accepted Answer · 2019-06-05 11:52:15Z

3

Answers to what is appropriate or what is a good style can be only opinion based. I don't have a strong opinion on this subject, but I can see some decision points:

1) Sparx Systems Enterprise Architect can draw synchronous messages with "implicit return message" as shown here: http://www.sparxsystems.com/resources/uml2_tutorial/uml2_sequencediagram.html

Just 1 line (not 2 lines). Simpler diagram, easier to read.

2) Google: "uml sequence diagram best practices" returns several resources with pros/cons.

3) Usually when a decision like this is needed, following the path of least resistance (only 1st few miles paved..) also known as KISS principle is a good guide

edited Jun 5, 2019 at 11:52

robalem

1674 silver badges20 bronze badges

answered Aug 20, 2014 at 17:51

xmojmr

8,1765 gold badges33 silver badges54 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Thanish Over a year ago

IMO, a drawback with the first example is that, when the arrow direction changes, the request and response parts of the text also change. I prefer the second method because it makes it easier to identify the request or the response separately. Saves a few µs in your head. Check creately.com/blog/diagrams/sequence-diagram-tutorial/#Notations for some examples for both. (I work at Cinergix but I didn't write this article)

Collectives™ on Stack Overflow

What is the appropriate way to model API requests in Sequence Diagrams?

1 Answer 1

1 Comment

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Related