12

I am developing a RESTful API. This is my first API, but also my first really big coding project. As such, I'm still learning a lot about architecture etc.

Currently, I have my api setup in the following layers:

  • HTTP Layer
  • Resource Layer
  • Domain Model / Business Logic Layer
  • Data Access / Repository Layer
  • Persistent Storage / DB Layer

The issue I have run into at the moment is where do I need to put workflow objects / managers? By workflows, I mean code that evaluates what next step is required by the end user. For example, an e-commerce workflow. User adds item to basket, then checks out, then fills in personal details, then pays. The workflow would be responsible for deciding what steps are next, but also what steps are NOT allowed. For example, a user couldn't cause errors in the API by trying to pay before they have entered personal details (maybe they recall the URI for payments and try to skip a step). The workflow would check to see that all previous steps had been completed, if not, would not allow payment.

Currently, my workflow logic is in the Resource Layer. I am using hypermedia links to present the workflow to the user e.g. providing a 'next step' link. The problem I have with this is that the resource layer is a top level layer, and more aligned with presentation. I feel it needs to know too much about the underlying domain model to effectively evaluate a workflow i.e. it would need to know it has to check the personal_details entity before allowing payment.

This now leads me to thinking that workflows belong in the domain model. This does make a lot more sense, as really workflows are part of the business logic and I think are therefore best placed in the domain layer. After all, replace the Resource Layer with something else, and you would still need the underlying workflows.

But now the problem is that workflows required knowledge of several domain objects to complete their logic. It now feels right that it maybe goes in its own layer? Between Resource and Domain Layer?

  • HTTP Layer
  • Resource Layer
  • Workflow Layer
  • Domain Model / Business Logic Layer
  • Data Access / Repository Layer
  • Persistent Storage / DB Layer

Im just wondering if anyone had any other views or thoughts around this? As I said, I have no past application experience to know where workflows should be placed. Im really just learning this for the first time so want to make sure I'm going about it the right way.

Links to articles or blogs that cover this would be greatly appreciated. Love reading up on different implementations.

EDIT

To clarify, I release that HATEOAS allows the client to navigate through the 'workflow', but there must be something in my API that knows what links to show i.e. it is really defining the workflow that is allowed. It presents workflow related links in the resource, but additionally it validates requests are in sync with the workflow. Whilst I agree that a client will probably only follow the links provided in the resource, the danger (and beauty) of rest, is that its URI driven, so there is nothing stopping a mischievous client trying to 'skip' steps in the workflow by making an educated guess at the URI. The API needs to spot this and return a 302 response.

GWed
  • 15,167
  • 5
  • 62
  • 99

4 Answers4

3

The answer to this question has taken me a fair bit of research, but basically the 'workflow' part has nothing to do with REST at all and more to do with the application layer.

My system was had the application logic and REST API too tightly coupled. I solved my problem by refactoring to reduce the coupling and now the workflow lives within the context of the application

GWed
  • 15,167
  • 5
  • 62
  • 99
1

REST encourages you to create a vocabulary of nouns (users, products, shopping carts) against an established set of verbs (GET, POST, PUT, DELETE). If you stick to this rule, then in your example the workflow really is defined by the set of interactions the user has with your site. It is how the user uses your app, which is really defined by the UI. Your REST services should react appropriately to invalid state requests, such as attempting to checkout with an empty cart, but the UI may also prevent such requests using script, which is an optional characteristic of REST.

For example, the UI which displays a product to the user might also display a link which would permit the user to add that product to their cart (POST shoppingcart/{productId}). The server really shouldn't care how the user got to that POST, only that it should add that product to the user's cart and return an updated representation of the cart to the user. The UI can then use javascript to determine whether or not to display a link to checkout only if the shopping cart has one or more items.

So it seems that your workflow lives outside the REST service and is rather defined by the navigation in your pages, which interact with your REST services as the user requests things. It's certainly possible that you might have internal workflows which must occur within your application based on the states setup by the user. But what you seem to be describing is a user interaction within the site, and while that's indeed a workflow, it seems better defined by your UI(s) than by a dedicated server-side component/layer.

Keith Stauffer
  • 11
  • 1
  • I disagree with what you have said. A REST API uses HATEOAS to allow the user to define a 'workflow' through the app. But what you are saying is that we should allow the user (or client app) to define the logic and to do anything they want!! This is clearly wrong. So what I am talking about is ensuring that the 'workflow' that the client is following is allowed. Some part of the API must be responsible for working out what links are allowed to be displayed with a resource (the workflow) and also validating that requests aren't outside the workflow (e.g. return a 302) see update above – GWed Apr 24 '14 at 16:33
  • Because the server is providing javascript to the client which the client uses to determine whether or not to display a link, the server is essentially extending its logic onto the client, and is thus still determining the workflow. There's nothing to prevent you from injecting a business layer in your architecture between the UI and the REST services, but when you do so, depending on how you implement it, your UI may no longer be communicating RESTfully. – Keith Stauffer Apr 24 '14 at 16:34
  • And where would this business layer live? – GWed Apr 24 '14 at 16:38
  • Gaz: from your comment above "...there is nothing stopping a mischievous client trying to 'skip' steps in the workflow by making an educated guess at the URI" This is correct. When a user hits the url which posts a purchase with an empty cart, the server should verify that the cart is in a valid state before proceeding and return an error otherwise. The point is, the server should take reasonable precautions on posts/puts/deletes to make sure the state passed by the client is valid. It does this by examining what the client sent, which should be everything it needs to satisfy the request. – Keith Stauffer Apr 24 '14 at 17:13
  • I think you REST services *are* the business layer, combined with the client's use of server-sourced script. You can make the objects as complex as you wish, so long as when you pass an object from the client to the server, it encompasses all that the server needs to handle the request. For a purchase, that could be a userId which the server uses to lookup the user's current shopping cart with, or it could be the shopping cart itself. JSON is a good thing. :) – Keith Stauffer Apr 24 '14 at 17:25
1

You touch on the workflow (aka business logic) part of an API. Technically this is a separate concern from the API part which is the interface. Sure, as you mention, HATEOAS allows you to suggest certain actions which are valid, but you should be careful to maintain statelessness.

In REST applications, there must not be session state stored on the server side. Instead, it must be handled entirely by the client.

So, if there's session state on the server, it's not REST.

For your shopping cart example, you can save state in a separate caching layer like Redis. As for your workflows. You wouldn't want to put business logic like calculating their shopping cart or total bill in a domain model. That would be added to service layer.

You talked about mischievous users guessing URLs. This is always a concern and should be handled by your security. If the URL to delete a user is DELETE /user/3782 ... they can easily guess how to delete all the users. But you shouldn't rely only on obfuscating the URLs. You should have real security and access checks inside your endpoints checking if each request is valid.

This is the same solution for your shopping cart concerns You'll need to grant a token which will attach their shopping information and use that to validate each action, regardless if they knew the right URL or not. There are no shortcuts when it comes to security.

Community
  • 1
  • 1
Erich
  • 2,743
  • 1
  • 24
  • 28
-1

You may want to re-orient your architecture along the lines of DDD (Domain Driven Design) and perhaps use a MSA, that way you can shift from orchestrated workflow to EDA and choreography of micro processes.

Sood
  • 169
  • 1
  • 6
  • Why? Maybe provide some pros and cons. What do the other acronyms stand for? A very 'management' answer so far. – GWed Jun 21 '16 at 12:46