restrestful-architecturemethodology

Struggling with REST and Larman's (RCP?) system operations


In Craig Larman's book Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development (3rd Edition), a use case is converted to a System Sequence Diagram (SSD) which contains system operations. It's a way of doing high-level design first, that's easily traceable to the requirements (use case), and later refining it by detailing the system operations at the domain level via OO design principles.

I'm trying to understand this methodology using RESTful services. The trouble spots seem to be with resources and the stateless operations.

Here's a sample from the book, an SSD with four system operations:

Example of a SSD - System Sequence Diagram

An SSD is also an abstraction of the presentation layer (on the left) and the domain layer (on the right). The domain layer might also include the application and or business logic.

In Larman's approach, a system operation (e.g., makeNewSale()) should be handled by a GRASP Controller which is a domain non-presentation-layer object that handles the system operation.

Now, let's say we're trying to use RESTful services in this approach:

So, assuming my understanding up to now is right, my questions are:

  1. Does the Uniform Interface constraint of REST respect loose coupling of presentation/domain layer separation? At first, it seems to be a detail of the presentation layer (like an actionPerformed() method in Java Swing). But the part that bothers me is that http://...com/sales ties right into a Sale (which is a domain) object.

    Another way of putting it: by creating REST resources and REST verbs accessing them via a Uniform Interface, isn't application/business logic being put into to the presentation layer? Larman's SSD approach is about layers and he explicitly states that application logic should not go in the presentation layer. For example, a POST to http://...com/sales creates a new sales/001 resource and also sends makeNewSale(). The first part seems like business logic. The fact that my REST resource names follow many of my Domain object names seems like my Presentation layer is (more) coupled to my Domain layer, than if I were using Swing and only called makeNewSale() from an actionPerformed() on a JButton.

  2. Larman's SSD concept is oriented towards the RCP model (with state in the server), but can an SSD be made to easily jibe with a REST philosophy? For example, endSale() exists to break the system out of a loop of enterItem() calls. Later in the book, Larman even presents a state diagram about this:
    State diagram for DSS
    I read about How to manage state in REST and it seems one has to take care with passing state on each system operation if needed (as in the authentication token example above), or the "state" is actually encapsulated in the resources. I thought about it, and with REST, endSale() could probably be removed entirely.

I used a concrete example here, so that the answers can also be concrete.


Solution

  • I'll try to address your questions, but keep in mind that this is a very much debatable topic..

    1. The REST Uniform Interface does respect the separation of concerns between presentation and business logic. The separation is about the presentation layer not knowing details about the implementation of the business logic and vice-versa, but there is no point in hiding what can be done with a domain entity (i.e. the services that are available for a resource). What you want to hide is how the actions are executed.

    2. The REST's HATEOAS principle dictates that the representation of a resource (the instance of a domain entity) should encapsulate the state of the client/server interaction, so the services should return that state to the client one way or another. This, and the use of hypermedia (i.e. links to available services - representing actions that can be done on a resource, given its state) should map quite easily to the state diagram you posted.

    Let's continue with your example :

    let's say that there is a service newSale returning a Sale object. This service must be invoked using the POST method. in the Sale's hypermedia section there are 2 links, one to the addItem service (which is also a POST and accepts an updated version of the Sale object, returning it after it has been saved), and one to the endSale service (also a POST), which saves the Sale and marks it as 'complete'. This last service does not return any resource representation, just the http response OK if the object is succesfully saved.