REST Documentation – How to Document a REST Interface with a Flowchart

documentationflowchartrest

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.

Best Answer

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

Related Topic