Nowadays it is very common for enterprise applications to share data and business logic with other applications. This can be easily achieved using web services. This becomes very tricky when providing omni channel support in E-commerce (accessing site using android or any other native application).
ATG allows developers to create their own webservices along with pre-packages services.
These pre-packages services are available in below modules.
- DAS.WebServices
- DPS.WebServices
- DCS.WebServices
ATG supports two types of REST webservices (webservices APIs).
- Legacy REST API
- REST MVC API
Here I am going to explain REST MVC.
Steps to create New REST MVC Call
- Create Actor.
- Define Actor chain(s) for that actor.
- Register Actor with ActorChainRestRegistry.
- Create Bean filter (optional).
Steps to create REST Actor
- Create Component of atg.service.actor.ActorChainService class.
- Define actor chains for this component (xml configuration).
- 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)
=======================================================================
<?xml version="1.0" encoding="UTF-8"?>
<actor-template default-chain-id="sayHello" xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/actorChain_1.0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<actor-chain id="sayHello" transaction="TX_SUPPORTS">
<component id="sayHello" name="/com/test/web/HelloWorld"
method="sayHello">
</component>
</actor-chain>
</actor-template>
=======================================================================
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.
- Component Actor
- Droplet Actor
- Form Actor
- JSP Actor
- Nested Actor
- 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.
- Java bean filtering.
- Repository item filtering.
Steps to configure filter
- Layer /atg/dynamo/service/filter/bean/beanFilteringConfiguration.xml
- Configure filter in this file
- Refer this filter in actor chain
- 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.
=======================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bean-filtering SYSTEM "dynamosystemresource:/atg/dtds/beanfilter/beanFiltering_1.0.dtd">
<bean-filtering>
<repository name="/atg/userprofiling/ProfileAdapterRepository">
<item-descriptor name="user">
<filter id="customDetail" default-include="false">
<property hidden="false" name="firstName"/>
<property hidden="false" name="lastName"/>
</filter>
</item-descriptor>
</repository>
</bean-filtering>
=======================================================================
Using filter in actor chain.
=======================================================================
<?xml version="1.0" encoding="UTF-8"?>
<actor-template default-chain-id="summary" xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/actorChain_1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<actor-chain id="customDetail" transaction="TX_SUPPORTS">
<component id="profile" name="/atg/userprofiling/Profile" invoke-method-requires-session-confirmation="true" component-var="profile" set-property-requires-session-confirmation="true">
<output id="profile" filter-id="customDetail" name="profile" value="${profile.dataSource}"/>
</component>
</actor-chain>
</actor-template>
=======================================================================
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=<ruleset>\n <accepts>\n <rule op\=and tag\="Show">\n <rule op\=and tag\="Content">\n </rule>\n <rule op\=and tag\="Environment">\n <rule op\=gt>\n <valueof target\="securityStatus">\n <valueof constant\="3">\n </rule>\n </rule>\n </rule>\n </accepts>\n</ruleset>
=======================================================================
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
