Beyond Brochureware: Building Web Applications with JSS and RESTful HATEOAS Services

Sitecore is not only a tool for marketing to new customers, it is a full-featured experience management that can (and often should) be used throughout the customers journey.  Historically I have seen Sitecore customers have excellent marketing and commerce sites but once a prospect makes a purchase and becomes a customer, they are introduced to below par, static web (or mobile) applications to do thinks such as manage their user accounts, interact w/ their products, and other types of interactions with us. Sitecore can fill the gap here with it's ability to update content, change experience, etc. BUT remember, Sitecore is an experience platform, not the place to deploy all business logic in the entire enterprise.  

For situations like this you must ask yourself, how can I apply the software engineering principle of separation of concerns to this situation?  The answer to me was obvious, Sitecore JSS and HATEOAS microservices.

What is HATEOAS?

HATEOAS is an acronym for Hypermedia As The Engine Of Application State.  Very important to understand this, if you do not know what hypermedia is, please review my previous post on RESTful APIs. The Engine Of Application State simply refers to state transitions or a state machine, what is my current state and given that state, what are the things I can do?  I came across a great talk on this here which you should definitely check out.  

Example Scenario: Suppose I purchase a product that comes with a subscription and that subscription account is managed through an Account Management application.  The application interaction may go like this:

What the API is doing in this example is orchestrating a flow based on the HTTP protocol and RESTful standards.  So the business rules that are stated here are as follows:

1. You must verify your identity before you can see your account information.
2. Okay, now you may see your account information but your account is in an invalid state so display the message which is defined as "account.missing.primary".
3. The only next step you can take is add an email to the resource collection /accounts/(my)/emails.

Next, the front-end could call the endpoint /accounts/(my)/emails and maybe the response looks something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

21
22

23

{
   "data": [],
   "_links": {
     "self": "href": "/accounts/(my)/emails", "allow": ["get", "post"],
     "account": { "href" : "/accounts/(my)", "allow": [ "get" ]
   },
   "_embedded": {
      "schema" : { "data" : [{
        "$schema": "https://json-schema.org/draft-04/schema#",
        "title": "post-emails",
        "type": "object",
        "properties" : {
           "email": { "type": "string", "format": "email" },
           "isPrimary": { "type": "boolean", "enum": [ true ]},
         },

         "required": [ "email", "isPrimary" ] },

      }],

      "_links": {
        "self": "href": "/accounts/(my)/emails/(schema)", "allow": [ "get" ]
      }
   }
}

So now the API defines schema of objects that it will accept pushing data and schema validation rules to the API.  As the data is modified (the State changes) then different options com available but notice there is nothing returned that will define a screen or user experience.

HATEOAS and Sitecore JSS

In Sitecore we will define components/renderings and data sources that present how the users can interact with the API resources, and dictionaries that translate labels, error messages, and other data returned from the APIs. When done correctly, you will see the JavaScript will contain very little business logic itself and the front-end very loosely coupled to the business rules and domain of the API but at the same time tightly coupled to the standards and protocols of REST. 

This creates what is called a federated mircroservice architecture.  Each microservices can be updated and deployed independently of the front-end, and the same is true with the front-end. Sitecore content, renderings, A/B tests etc. can be modified or added to change the user experience independent of business domain logic. If there are changes to business logic, those changes can be deployed into the API and new data validations, flows, or business rules will be enabled with no change to the presentation logic (usually), maybe just additional dictionary items will be needed which does not require a deployment.

Example Logical Architecture 

Summary

I wrote this post to share my currently favorite architecture for building experience managed web applications.  The architecture presented here is extremely flexable, reduces lead time for change, scales well both from team prespective (can add teams by adding/splitting miroservice domains) and a application performace perspective (designed to scale horizontally, especially when combined with CQRS patterns).  Try this architecture out, I think if you do it will be a favorate architecture of yours as well.

Other Resources: