ATG REST MVC Basics

ATG REST MVC Basics

A lot of us might've heard the term ATG REST or REST API but a lot of us don't get a chance to work on it OR don't exactly know what it is OR why do we exactly use it.
We will cover everything right from the basics as we always do.

What is REST?

You might've googled it a lot of times, and a lot of websites simply say REST stands for Representation State Transfer, along with some weird content which none of us understand. Let us understand what is REST and why is it used.

Let's take a basic scenario, wherein an order is submitted on a website, and all the details of the order (items, cost of each item, order total, time of placing order etc.) has to be sent to another system (for auditing purposes). The two systems are entirely different, one that hosts an eCommerce website with all the eCommerce functionality; and another system just takes order details and saves it for auditing purposes for calculation of monthly revenue, monthly profit, calculation of most sold items etc.
The architectures of these two systems are entirely different, and there may be a possibility that two different organizations handle them. The architecture of one system may not be known by another system.
In such a case, the order details have to be sent in a format which can be read by both the systems. For this purposes, XML or JSONs are used.
This is the example of order details in XML or JSON formats:

orderDetails: { "orderId":"ord123456", "orderTotal": 400, "orderSubmitDate": "23-NOV-2018 13:33:44:00"
 "items": [{  "itemId": "itm100002",  "itemName": "Sun Shine",  "listPrice": 300,  "discount": 0 }, {
  "itemId": "itm100003",  "itemName": "Sun Shine",  "listPrice": 200,  "discount": 0 } ]}

These pre-packages services are available in below modules.

1.       DAS.WebServices

2.       DPS.WebServices

3.       DCS.WebServices 

ATG supports two types of REST webservices (webservices APIs).

1.       Legacy REST API

2.       REST MVC API

Here I am going to explain REST MVC.

Steps to create New REST MVC Call

1.Create Actor.

2.Define Actor chain(s) for that actor.

3.Register Actor with ActorChainRestRegistry.

4.Create Bean filter (optional).

Steps to create REST Actor

1.Create Component of atg.service.actor.ActorChainService class.

2.Define actor chains for this component (xml configuration).

3.Point definitionFile property of the component to xml file created in step 2.

Below is the example of Hello World Actor

#/com/test/web/actor/HelloWorldActor.properties
$class=atg.service.actor.ActorChainService
definitionFile=/com/test/web/actor/helloWorldActor.xml

Actor Chain definition file (helloWorldActor.xml)
 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
                  method="sayHello">
     
  

Registering this actor with ActorChainRestRegistry 

To register this actor you need to add the actor path with chain id to registeredUrls property of /atg/rest/registry/ActorChainRestRegistry component.

One important thing to remember here is ,that you are registering actor chain not actor. In the case there are more then one chains defined for that actor you need to register each one here. In  other words you can say each chain ID should be registered separately.

By default, no actors are registered.

In below code snippet we are registering sayHello chain.  

#/atg/rest/registry/ActorChainRestRegistry.properties 
registeredUrls=\
         /com/test/web/actor/HelloWorldActor/sayHello 
 

 ATG REST MVC Supports below Actor Types.

1.Component Actor 

2.Droplet Actor

3.Form Actor

4.JSP Actor

5. Nested Actor

6.Variable Actor 

Filtering in MVC REST

Filtering is used in REST MVC to control the property in the response object. In other words filter is way to configure which properties will be available in the response object. This is to avoid unnecessary data in the response.

REST MVC support two types of filters.

1.                   Java bean filtering.

2.                   Repository item filtering.

3.                    

Steps to configure filter

1.Layer /atg/dynamo/service/filter/bean/beanFilteringConfiguration.xml 

2.Configure filter in this file

3. Refer this filter in actor chain

4.ATG recommends 3 types of filters

                   Short

                   Summary
                   Detailed

Once filter is defined you can use filter in actor chain using filter-id attribute.

Filter definition example.

    

   

  
     
             

  Using filter in actor chain.  

       

 

 

Note : It is best to define a filter for every object, so that you can control its output. Note that if an object has no filters defined, it will output all properties.

Configure Security in REST MVC 

Once REST call is implemented then It is time to secure it. Security is crucial to avoid unauthorized access.  

Follow below steps to secure rest webservice 

·                     Create the RuleSetService.

·                     Create Access Controller.

·                     Add mapping from actor chain to Access Controller in /atg/dynamo/servlet/dafpipeline/AccessControlServlet. 

CustomRuleService (Only logged in user can access).

#/atg/rest/CustomRuleSetService.properties

$class=atg.targeting.RuleSetService
updatesEnabled=true
rulesFileCheckSeconds=0

# Use must have securityStatus 4 or higher (EXPLICIT-SIGNIN, SECURE-SIGNIN, CERTIFICATE)
ruleSet=\n  \n    \n      \n      \n      \n        \n          \n          \n        \n      \n    \n  \n

CustomAccessController

#/atg/userprofiling/CustomAccessController.properties

$class=atg.userprofiling.RuleAccessController
enabled=true
# Rules used to determine whether access should be allowed
ruleSetService=/atg/rest/CustomRuleSetService
# URL to redirect to if access is denied
deniedAccessURL=/rest/model/atg/userprofiling/SecurityStatusActor/authenticationRequired

 AccessControlServlet

#/atg/dynamo/servlet/dafpipeline/AccessControlServlet.properties

accessControllers=\
    /com/test/web/actor/HelloWorldActor/sayHello=\
         /atg/userprofiling/CustomAccessController

      

ATG REST MVC Key Points

·                     Get and Post are supported.

·                     Access restriction  by AccessControllerService.

·                     Also support implicit objects (session, request).

·                     URL syntax http://host:port/rest/model/actor_component/tail.

ATG REST MVC Key Components

·                     /atg/rest/Configuration/ 

·                     /atg/rest/registry/ActorChainRestRegistry/

·                     /atg/dynamo/service/filter/bean/XmlFilterService

·                     /atg/dynamo/service/actor/ActorChainValidationService