ACC TIP | Build REST over SOAP API

If you’re familiar with Adobe Campaign Classic, you may have noticed that it utilizes the SOAP (Simple Object Access Protocol) API.

We live in an age where REST is taking over, and the good old XML SOAP is slowly being forgotten. To me, as an old-timer, I can confidently say that it doesn’t make any difference because both are used for the same purpose: making systems work together.

Despite being widely used when ACC was released back in 2001, SOAP has since become less popular in favor of newer APIs. However, Adobe Campaign Classic still utilizes SOAP, and understanding its functionality is crucial for successful integration.

For wrapping SOAP with REST we will use NL.API.init from api.js (xtk) library. Here’s an explanation of how to use this library:

1. Import the necessary server-side dependencies:

    loadLibrary('/nl/core/shared/nl.js')//(required) bootstrap to NL framework 
    // with above we can use NL.reuire()  it is basically same as loadLibrary() with additional steps 
	// of checking if the library has not been loaded already before
	NL.require('/nl/core/shared/xtk.js')//(optional) Shared functions to manipulate XTK data and datatypes
	.require("xtk:shared/json2.js")//(optional) if you need to manipulate json object
    .require("/nl/core/api.js")// (required)
    .require('/nl/core/jsspcontext.js')//(required)

2. Call the NL.API.init function to initialize the API with default behavior:

NL.API.init = function(request, response, options, callback) 

The init function takes four parameters:

• request: The HTTP request object.
• response: The HTTP response object.
• options: An object containing additional options for API initialization.
• callback: A function responsible for generating the API call, which takes the jsspContext as an argument.

3. Configure the API initialization options: The options object can have the following properties:

• jsonOutput (Boolean, default: false): Set it to true to have JSON output content type.
• authentication (Boolean, default: true): Set it to false to implement an API call without authentication.
• escalationToken (Object): An object containing an optional login property for privilege escalation.

4. Implement the callback function: The callback function is responsible for generating the API call. It takes the jsspContext as an argument and should contain the logic for processing the API request.
5. Additional functionality: The code snippet also includes cache control headers and content type configuration based on the provided options. It handles authentication and privilege escalation if applicable.

If you take a look at the line 88 of ‘api.js’ library, you will see the authentication process handled by ‘xtk:jsspcontext.js’ library. From where we can see the our API call will accept session token in query parameters or in POST request, unless the authentication is not switched off.

Authentication

You can use sessiontoken with GET, POST and cookie to authenticate to the API service. If you do not want to use authentication at all you can turn it of by setting the property authentication to false. This can be used for ping monitoring service, where all server vitals are monitored by another monitoring tool eg. splunk.

GET __sessiontoken

Session token passed in GET request. GET requests can be cached by browsers, stored in browser history, logged in web server logs, and displayed in the URL bar. If a security token is included in the URL of a GET request, it can potentially be exposed in these places, making it easier for attackers to exploit it.

POST header X-Security-Token

Session token passed in POST header ‘X-Security-Token’. Since POST requests do not expose the parameters in the URL, they provide an extra layer of security compared to GET requests. However, it’s important to note that POST requests are not immune to attacks. They can still be vulnerable to other types of security threats, such as cross-site scripting (XSS) or SQL injection, if proper security measures are not implemented.

Session token

You can obtain session token with another call that the REST will follow. We can show it on example inside Adobe Campaign Classic workflow in JavaScript activity.

var http = new HttpClientRequest("https://example.com/nl/jsp/saprouter.jsp"),
    token,
    response,
    document;

http.header["Content-type"];
http.header['SOAPAction'] = "xtk:session#Logon";
http.method = "POST"
http.body = <soapenv:Envelope>
   //SOAP XML REQUEST AS IS IN WSDL FILE 
  //..
  //..
  //SOAP XML REQUEST AS IS IN WSDL FILE 
</soapenv:Envelope>;

http.execute();
response = http.response;

if(response.code == 200){
//parse out the session token
  document = response.body.toDocument();
  token = document.getElementByTagName("pstrSessionToken");
}

Example

 // as we are in JSSP you can also use page directives to import libraries
 // <%@ page import="/nl/core/shared/nl.js"%>
  <%  
    loadLibrary('/nl/core/shared/nl.js')
    //with above we can use NL.reuire() instead loadLibrary()
	NL.require('/nl/core/shared/xtk.js')
	.require("xtk:shared/json2.js")
	.require("xtk:common.js")
    .require("/nl/core/api.js")
    .require('/nl/core/jsspcontext.js')//for authentication

 NL.API.init(request, response, {
    jsonOutput: true
    }, function(jsspContext) {
            response.addHeader("Pragma", "no-cache")
            response.addHeader("Cache-Control", "no-cache");
            response.addHeader("Expires", new Date().toGMTString());
            
            //do something resty
   			//ot call other SOAP libraries as needed
   
            document.write(JSON.Stringify({result:"some result"}));
    });
%>

Newly created REST API is then called:

https://example.com/namespace/jsspPageName.jssp

With “wrapping SOAP to REST” methods or even create new ones to provide a more familiar and straightforward interface for developers who are accustomed to working with RESTful services.

Please leave this field empty

Oh hi there
I have a FREE e-book for you.

Sign up now to get an in-depth analysis of Adobe and Salesforce Marketing Clouds!

Email Address *

We don’t spam! Read our privacy policy for more info.

Check your inbox or spam folder to confirm your subscription.