REST Client UDR Types

Owned by Jenni Wallin
Last updated: Jul 01, 2024 by Hazren Sulaiman
4 min read

RESTCycleUDR

The RESTCycleUDR type is used to pass data between the workflow and REST Client agent. 

FieldDescription
Context (any)

This field that can be used in the workflow configuration to keep track of, and use, internal workflow information related to a request from the REST Client agent.

For instance, before you route a RestCycle UDR to the REST Client agent, store the TCPIPUDR from a TCP/IP collection agent in the Context field. You can then read the TCPIPUDR from the Context field in the RESTCycle UDR that contains the response from the REST Client agent, and use it to send back a response to the TCP/IP collection agent.

Error (RESTError(RESTClient)) 
This field contains information related to internal processing errors.
Request (RESTRequest(RESTClient))This field contains the request from the REST Client agent to the server.
RequestSentTime (long)This field contains the timestamp from before the REST request was sent.

Response(RESTResponse(RESTClient))

This field contains the response from the server to the REST Client agent.
ResponseReceivedTime (long)This field contains the timestamp from when the REST response was generated.
SessionId (string)This field contains a string representation of a random UUID.

The nested UDR types of RESTCycleUDR are described below.

RESTRequest

FieldDescription
Body (bytearray)This field contains the HTTP message body.
Header (map<string,string>)

This field may contain an HTTP header. The header fields are stored as key-value pairs.

The REST Client agent will override any values that you set in the Authorization field of the header.

Method (string)

This field must contain the HTTP method. The REST Client agent does not validate the specified method and any string value is considered valid.

Params (map<string,string>)

This field may contain HTTP parameters that are passed in the query string. The parameters are stored as key-value pairs.

ResourceURI (string)

This field contains a resource URI, relative to the base URL that is configured in the REST Client agent.

ResourceURI must begin with a slash character, e g "/search".

Example - Creating a REST request in APL

import ultra.RESTClient;
consume {
 RESTCycleUDR aUDR = udrCreate(RESTCycleUDR);
 RESTRequest req = udrCreate(RESTRequest);

 //Create and set header
 map<string,string> header = mapCreate(string,string);
 mapSet(header,"Accept","*/*" );
 req.Header = header;
 
 //Set HTTP method
 req.Method = "GET";
 
 //Set resource URI
 req.ResourceURI="/get";
 
 aUDR.Request = req;
 udrRoute(aUDR);
}

RESTResponse

FieldDescription
Body (bytearray)This field contains the HTTP message body.
Header (map<string,string>)This field may contain an HTTP header. The header is stored as key-value pairs.
ResponseCode (int)This field contains the response code from the server.

Example - Receiving a REST response in APL

import ultra.RESTClient;
consume {
	if (instanceOf(input,RESTCycleUDR)) {
	    RESTResponse resp = udrCreate(RESTResponse);
	    resp = ((RESTCycleUDR)input).Response;
   		debug("Response Code:" + resp.ResponseCode);
		list<string> mKeys = mapKeys(resp.Header);
        for(string i:mKeys) {
            debug("Header:" + i + "=" + mapGet(resp.Header,i));
        }              
		debug(baToStr(resp.Body));
    }
} 

Note!

HTTP redirect is currently not supported. When the response code is 301 (Moved Permanently) or 302 (Found), the REST Client agent will not follow the URL in the header.

In order to handle redirects, you must check the ResponseCode field in the RESTResponse UDR. If the value is 301 or 302, you must configure the APL code to send a new request to the URL that is specified in the Location field of the header.

Hint!

When the body field contains a JSON formatted string, you can use the APL function jsonDecode to decode the contents. For further information about this function, see 21. JSON Functions in the APL Reference Guide.

When the body field contains XML data,  you can use the XML schema support in Ultra to decode the contents. For further information about XML and Ultra, see 18. XML Schema Support in the Ultra Reference Guide.

RESTError

FieldDescription
ErrorCode (int)

This field contains an internal error code:

0 - No error

1 - The response time from the remote server exceeded the timeout value of the agent.

2 - The number of outstanding requests exceeded the maximum value of the agent.

3 - The OAuth access token has become invalid, possibly due to expiration.

4 - Unable to refresh token. This error will be returned if the agent has tried to refresh the token 10 times without success.

5 - The response payload size exceeded limit. To resolve this error, you can configure the max content length through topo configuration.

99 - Miscellaneous error.

Example - Handling errors APL

import ultra.RESTClient;
consume {
    if (instanceOf(input,RESTCycleUDR)) {    
        if(((RESTCycleUDR)input).Error.ErrorCode!=0) {  
            udrRoute((RESTCycleUDR)input,"RESTCycleUDR_error");
        }  else {
			//...
        }
    }
}

OAuth2UDR

FieldDescription
accessTokenURI (string)

The URI where the access token can be obtained.

bodyParams (map,<string,string>)Some authentication servers may require additional parameters in the body of the token requests, these go into this field in a map format.
clientId (string)The unique client identifier issued by the authorization server.

clientSecret (string)

The client secret.
grantType (string)

The grant type; either client credentials or resource owner password credentials.

overrideBaseURL (string)Determines whether the BaseURL may be overridden or not.
password (string)The password associated with the username.This is mandatory when grant type is resource owner password credentials.
username (string)The resource owner username, i e end-user granting access to a protected resource. This is mandatory when grant type is resource owner password credentials.

If the REST Client agent consumes a new UDR, it will execute Authentication.