CA Live API Creator 5.0

5.4 5.3 5.2 5.1 5.0 4.1 4.0 3.2 3.1.1 3.1
English

The req Object

The req Object
lac42
The 
req
 object describes the request that 
CA Live API Creator
 processes. Access the object as the 
req
 variable in rules and in event handlers
This object is suitable for transaction state but not for state that transcends requests. 
CA Live API Creator
 creates this object once per request and discards its contents when the request is complete. 
In this article:
The req Object Attributes
The 
req
 object has the following attributes:
Attribute
Type
Description
clientAddress
string
The IP address of the caller initiating the request.
Example:
The following code snippet illustrates how you can reject requests that do not originate from the allowed IP range:
// Reject requests that do not originate from the allowed IP range
if ( ! req.clientAddress.match(/^12\.34\.56\./g))
   throw "Requests are not allowed from this IP address"
clientUsesHttps
boolean
Values:
  • True if the request is over HTTPS.
  • False if the request is over HTTP.
urlParameters
object
The parameters, and their values, as specified in the URL.
Example:
req.urlParameters.<paramName>
The following code snippet illustrates how you can require that the call provide a special parameter to create a widget:
// We require a special parameter to create a Widget
if (req.verb == "POST" && req.resourceName == "Widget") {
   var special = req.urlParameters.specialParam;
   if (special != "Please")
      throw "You forgot the magic word.";
}
log.debug("clone event start");
if (req.urlParameters.clone !== null) {
  log.debug("cloning: " + row);
  var deepCopy = ["lineitemsList"];
  SysLogic.copyTo("orders", logicContext, deepCopy, false); 
  }
apiKey
ApiKey
The authentication token that
CA Live API Creator
 uses to authenticate the request.
apiVersion
ApiVersion
The API version object. You can get its name by calling 
getName()
 (for example, 
v1
).
verb
string
GET, POST, PUT, DELETE
Example:
The following code snippet illustrates how you can require deletes to be over HTTPS:
// Deletes must be over HTTPS
if (req.verb == "DELETE" && !req.clientUsesHttps)
   throw "Delete must be over HTTPS";
resourceName
string
The name of the resource/table on which the request is performed.
baseUrl
string
The base URL on which the caller made the call.   
localBaseUrl
string
The base URL for this request, but corrected to use 
localhost
 as the host. Use this attribute if the caller must talk to (or loopback) the local API.
fullBaseURL
string
The full base URL for this request, including the API version.
localFullBaseURL
string
The full base URL for this request, but corrected to use 
localhost
as the host. Use this attribute if the caller must talk to (loopback) the local API.
httpHeaders
object
The HTTP headers that the caller provided, except the authentication header. Header names are case-insensitive.
Example:
req.httpHeaders['user-agent']
.
Strings in the 
req
 object are Java strings in
CA Live API Creator
. As a result, use care when using equality tests. The results from the '
===
' or '
!==
' equality tests can be unexpected. For example,
CA Live API Creator
 returns 
"GET" === req.verb
always as 
false
, where it returns 
"GET" == req.verb
as 
true
on GET requests.
The req Object Methods
The 
req
 object has the following methods:
baseUrl() Method
You can retrieve the base URL for the request, up to and including the API name, using the 
baseUrl()
 method. This method uses the following syntax:
[http: || https]://[server.company.com[:port[/ServerWAR]] ]/[rest || data]/[TeamSpace name]/[URL fragment]/
Example:
https://rest.acme.com/rest/default/data/
getUserProperty() Method
Use the 
getUserProperty()
 method to retrieve an arbitrary object from the request object, as previously set by the 
setUserProperty()
 method.
This method uses the following syntax:
req.getUserProperty(string, object)
setUserProperty() Method
Use the 
setUserProperty()
 method to set the specified API user property to the given value. After you have set the API user property, a piece of JavaScript code can retrieve the API user property in the scope of the request. 
This method uses the following syntax:
req.setUserProperty(name, object)
getUserProperties() Method
Use the 
getUserProperties()
 method to retrieve the URL properties/values where the property starts with 
arg
. 
Example:
req.getUserProperties().get("argName")
The apiKey Object Methods
The 
apiKey
 object contains information about the API user (the caller of the API) that are typically passed in from your authentication provider. The 
apiKey
 object includes the following methods.
getApiKey() Method
You can access the authentication token that 
CA Live API Creator
 generated to authorize the request using the 
getApiKey()
 method.
Example:
The following code example illustrates how you can get the 
apiKey
 object from the request:
var apiKey = req.
getApiKey()
; // apiKey as object
log.debug("** The apiKey: " + apiKey.getApiKey()); // gets apiKey as string 
getDataObjects() Method
You can access information about the API user that your authentication provider passes in using the the 
getDataObjects()
 method.
The following code example illustrates how to retrieve name/value pair information for an API user that is stored in the 
userData
 object of your HTTP authentication provider using this method:
var temp = req.apiKey
.getDataObjects
().get("abc");
log.debug("** The abc user data: " + temp);
For more information about how to authenticate API users using the HTTP authentication provider, see Authenticate API Users using an HTTP Authentication Provider.
getRoleNames() Method
You can retrieve a collection of user role name strings using the 
getRoleNames()
 method. This method uses the following syntax:
req.apiKey.getRoleNames()
Example:
var roles - req.getApiKey().getRoleNames()
getUserIdentifier() Method
You can retrieve the login ID (userIdentifier) from the authentication token using the 
getUserIdentifier()
 method. 
The following code example illustrates how you can get the name for an API user name within the authentication token:
var apiKey = req.getApiKey(); // apiKey as object
var login = 
apiKey.getUserIdentifier()
;
log.debug("** Get the login ID: " + login); // gets the login ID as string
hasRole() Method
You can retrieve a user role using the 
hasRole()
 method. This method uses the following syntax:
req.apiKey.hasRole('rolename')
This method returns
true
 if the caller has the requested
rolename
.
Example:
var isAdmin = req.apiKey.hasRole('admin');
Supply and Access HTTP Arguments
You can access arguments that are supplied in the HTTP request by way of the 
HttpServletRequest
 object. This object represents the raw HTTP request of type 
HttpServletRequest
. You can particularize your update requests by testing these arguments in your logic.
For more information:
Supply HTTP arguments, for example:
arg.argName=true
Access HTTP arguments in your rules using the following syntax:
req.getUserProperties().get(
"argName"
)
Explore the Contents of the Req Object
The following example shows how you can explore the contents of the 
req
 object using code:
var json = JSON.parse(req.json);
for (var i in req) {
    log.debug("****req " + i); }
for (var i in JSON.parse(req.json)) {
    log.debug("!!!!!json " + i);
}
var custName = json.customer; // a value in the request
log.debug("***custName: " + custName);
var options = { filter: "name = '" + custName + "'"
};
log.debug("***options: " + options);
var custAccount = SysUtility.getResource("cust", options);
for (var i in custAccount){
    log.debug("@@@@ " + i);
}
log.debug("***sending message" + JSON.stringify(custAccount[0]));
For more information about how to use the 
json
 object, including the 
stringify(<value>)
 
json
 object function, see JavaScript.
You can debug by way of logging information or using the 
debug
 option.
For more information about how to output messages to the log, see View Logging Information.