Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

3 Answers 3

up vote 9 down vote accepted

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

share|improve this answer
3  
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 '11 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 '11 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 '11 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 '11 at 12:08

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

share|improve this answer

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)
share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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