ART#403 - How does REST API Flow work in ATG?

Back



Next

Now that we have invoked our first REST Service, we will now understand the mechanism of how exactly does the flow of REST framework works in ATG. We'll study this in very simple steps.

1. The "Actor" Component

There was a time when we studied repository, and we discussed there are different repositories for different kind of data (e.g. ProfileAdapterRepository - for profile specific data, OrderRepository - for order specific date etc.). Each repository has its own ATG Component, and each component has a class called atg.adapter.gsa.GSARepository. So, if you need to create a brand new Repository, it must have a Component, and the component's class must be atg.adapter.gsa.GSARepository or its subclass. If you are not aware of this, your repository concepts need a little brush-up :) (Basic concept of repositories can be revisited HERE)

Similarly, every set of REST API Services has its own component, and it must use the OOTB class atg.service.actor.ActorChainService (or its subclass). Just like repositories, there are a number of OOTB "Actor" components viz.

/atg/userprofiling/ProfileActor - For Profile REST APIs
/atg/commerce/ShoppingCartActor - For Viewing Cart
/atg/commerce/order/purchase/CartModifierActor - For Cart Operations

Similarly, there are other OOTB actors too which represent a set of APIs. 
Each of these Actors use the class as atg.service.actor.ActorChainService
What is the function of these actors? Why are they necessary? How are they used? What are they used for? - We will discuss soon.

For now, the main point is for each set of REST Services, there is an actor component for which the class is atg.service.actor.ActorChainService. These actors can be created just like any other component - i.e. by creating a .properties file in the ATG's config-path.

Your sample component should look somewhat like:

2. Definition XML

Similar to repositories, the Actor components must also have a definition file. This file is also called the Actor Chain XML (not the official name, but this term is frequently used). We define something called "actor-chains" in this XML (similar to how we define "item-descriptors" in a repository XML). In these actor-chain XML blocks, you can invoke a component, invoke a droplet, call a JSP and a lot of other things. HOW? WHAT? - We will discuss soon.
Again, similar to the repository XMLs, the actor-chain XMLs are also placed in ATG config-path.
You can specify the actor-chain XML for a component in the "definitionFile" property of your Actor component. The value of this property should be the config-path of this XML.
If your actor-chain XML is at "/com/custom/mycustomactor.xml", then your Actor component should look like:-

Each block of actor-chain in the XML is identified by an "id". By this id, we know which actor chain to call. Example of an actor-chain block:-

Each XML can have multiple <actor-chain> elements, and each of them must be identified by a distinct "id" attribute.
In the above screenshot, we can see an <actor-chain> element, specified by an "id" attribute, and a droplet is being invoked inside the <actor-chain> element.

The above XML is for indicative purposes only - We will learn how to create actual XMLs in later sections, along with how we use this "id" attribute to invoke this actor chain and thereafter, the enclosed droplet.

3. URL Creation

In the previous article, we ran our first ATG REST Service, and we talked about how we use URLs to invoke an ATG REST Service. We also discussed that a URL has to be "hosted" in order to be used by postman, so that it can be hit and return a response. Well, let's have a look at how ATG constructs a URL for a service.
In the sections above, we saw that an "Actor" component and a supporting XML file (actor-chain XML) are needed. Since we are dealing with REST MVC api, the prefix of the URL will always be:
http://rest/model
[Port is optional, if you have apache redirect]
Next, we append the path of the "Actor" component. From the above example, lets say its /com/custom/MyCustomActor. You can use any other Actor component (custom or OOTB).
Therefore, the URL becomes:
http://rest/model/com/custom/MyCustomActor
Now we have reached till the right "Actor".
Next, we specify the id of the <actor-chain> to invoke. In above example, the id was "dropletInvocation" (see screenshot of xml-snippet). Again, this <actor-chain> could be OOTB or custom (and should belong to the xml "Actor" component you are using in the URL).
Finally, the URL becomes:
http://rest/model/com/custom/MyCustomActor/dropletInvocation
Since this actor chain calls a droplet (we just stated in (2) that it invokes a droplet), the droplet will be invoked in hitting this URL and it will return an output. In our example, it is returning a parameter with the name "outputString" with some value (let's say the value is "learn atg now!!").
Therefore, the resulting output will be somewhat like:

{
    "outputString":"learn atg now"
}

So that's how the basic flow of ATG REST MVC framework works. We will discuss the inner details for all these things very soon.


Back



Next