10

Does anybody have suggestions on creating a flowchart representation of a REST-style web interface? In the interest of supplying thorough documentation to co-developers, I've been toying around in dia modeling the interface for modifying and generating a product resource:

enter image description here

This particular system begins to act differently with user authentication/resource counts, so before I make modifications, I'm looking for some clarification:

  • Complexity: how would you simplify the overall structure to make this easier to read?
  • Display Symbol: is this appropriate for representing a page?
  • Manual Operation Symbol: is this appropriate for representing a user action like a button click?

Any other suggestions would be greatly appreciated.

My apologies for the re-post. The main stackexchange site suggested this question was better presented on programmers.

Improve this question

3 Answers 3

Reset to default
12

I feel Message Sequence Chart/Sequence diagram is better suited for documenting RESTful API interaction. What you have is a state diagram, while RESTful API by definition is stateless.

enter image description here

Improve this answer
5
  • 5
    The server in a RESTful architecture is stateless, however, the system itself is not. State is stored at the client, and possible state transitions are encoded within the representation of a resource so that the client can initiate the transition to a new state by making a request to the server. I think a state diagram is quite effective at communicating the overall system state, even if it doesn't precisely document the requests and responses between the client and server components.
    – Adam Jaskiewicz
    Jul 27, 2011 at 20:42
  • 1
    @Adam: you're right about overall system. But the question explicitly asks about documenting REST interface, not the whole system.
    – vartec
    Jul 28, 2011 at 7:37
  • Thanks, vartec, the MSC effectively documents the REST interface in this instance. I'm still curious to hear improvements to this model's documentation of the client's state.
    – James Kassemi
    Jul 28, 2011 at 23:30
  • 1
    RESTful systems that implement the hypertext constraint cause the client to act as a state machine. I have found using state machine type diagrams to be a far more effective tool for documenting RESTful client/server interactions.
    – Darrel Miller
    Aug 2, 2011 at 12:08
  • Is there possible to describe if-s and while-s in this diagram?
    – hellboy
    Jun 10, 2015 at 18:16
1

I definitely think a state machine is the right way to document that interactions of a RESTful system. However, I am still working on the right way to represent the hypermedia factors in the diagram. Here are a couple of experimental diagrams that I have done.

Maze

enter image description here

Improve this answer
0

My two pennies on the subject, as I am working with this at the moment:

  • focus on resources and their relations
    • and not on the action, and thus the HTTP method
    • when you follow a link, no matter if you did a GET or POST, your next possible states are dictated primarily by the current resource, and much less by the request's HTTP method

With that in mind:

  • remove some obvious links (i.e. to self, to root)
  • remove the relations' label if it just states "this [car] has a [owner]", where the source resource is car and the target resource is owner. It doesn't add anything
  • an interactive graph can be of great help with a complex state diagram (example)
Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.