Request Arguments

This section describes the available request arguments. The following arguments can be used by REST Web service operations.

restUrl

This is the URL of the REST service or resource in the form:

http://server:port/service/resource...

If you are using a custom endpoint, you can select the custom endpoint and map restUrl to the Url parameter in the custom endpoint.

Tip: You can use the custom endpoint for restUrl and the RESTCaller params input to add any required HTTP query string parameters to manipulate or retrieve the resource you want. For an example use case, refer to Using Custom Endpoints with RESTCaller.

options

The options control how the RESTCaller service creates the HTTP request that it sends to the REST service and how it translates the response from the REST service. Not all options apply to all RESTCaller operations as noted for the respective operation. Where the option does not apply, no action is taken.

returnJSONTypeHints
At times it is useful for the received XML element names to have type hint prefixes. The returnJSONTypeHints option makes it easier to copy received data to a send data structure since the elements defined in the sending and receiving XML structures can be declared using the same names. Set the returnJSONTypeHints option to true if this is desired.
returnAllHttpCodes
By default, for any HTTP return code from the HTTP service or resource that is not in the 2XX success range (such as 200, 201), the RESTCaller service throws a RESTCallerFault. Setting the returnAllHttpCodes option to true suppresses this behavior; this means the RESTCaller will return whatever HTTP return code the HTTP service or resource used to respond. This allows the orchestration workflow to explicitly process these responses. Note that RESTCaller can throw a RESTCallerFault for reasons other than an HTTP code that is out of the 2XX range.
copyResultsAsText
The RESTCaller will translate the response body to XML depending on the contentType of the HTTP service or resource response. To reduce the volume of extraneous data, if the data is translated to XML, the actual text of the response body not returned. You can set copyResultsAsText to true to instruct the RESTCaller service to return the body text, even if an XML translation was performed.
responseConversion
By default, the RESTCaller parses the response body, and translates it to XML depending on the contentType of the HTTP service or resource response. ContentTypes that are processed include:
- application/xml
- text/xml
- application/xhtml+xml
- application/json
Occasionally, the response content or its contentType may not correspond with one of these recognized contentType values. This option instructs the RESTCaller how to attempt to translate the body response. Note that if the response is not actually in the form that is specified, RESTCaller may throw a RESTCallerFault. The following values can be specified:
- CONTENTTYPE – This is the default. The response content type is used.
- XML – An XML response is assumed, and an attempt is made to parse the data to XML.
- JSON – A JSON response is assumed, and an attempt is made to parse the data to JSON.
- NONE – No format is assumed, and the response is returned as text.
sendAsJSON
By default, RESTCaller sends the operation bodyXML data argument as XML with the contentType value set to application/xml. If the service or resource expects JSON data, set this option to true to instruct the RESTCaller service to translate the bodyXML data to JSON and send the translated JSON data with the content type application/json.

Note: When you use the sendAsJSON option, you must declare a "JsonDoc" complexType element (with no namespace) under the bodyXML. For example, you can create a working data variable, “bodyXML”, of complexType, add JsonDoc as a complexType child element with no namespace, and then structure your request under JsonDoc. You then map the working data “bodyXML” to the RESTCaller bodyXML parameter. For more details, refer to Constructing Working Data XML to Map to JSON.
sendAsText
Sends the operation bodyXML data arguments as text with the contentType value set to text/plain. By default, the content type is set to text/plain but you can override this by setting a specific contentType with the sendThisContentType option.

Note: When you use the sendAsText option, you must declare a "TextDoc" string element (with no namespace) under the bodyXML. For example, you can create a working data variable, "bodyXML", of complex type, add TextDoc as a string child element with no namespace, and then assign the text string you want to send to TextDoc. You then map the working data "bodyXML" to the RESTCaller bodyXML parameter.
sendParamsAsFormData
Enables you to construct URL query parameters but have them sent as the body on a POST. URL parameters can be sent as part of the URL or via the params argument. Normally these are added together and sent as the URL query string, but with this option, any parameters on the URL remain part of the URL and any parameters passed using the params array argument are converted to a query string text that is sent as the body.

With this option, the content type is set to application/x-www-form-urlencoded but you can override this by setting a specific contentType with the sendThisContentType option. The bodyXML argument is ignored if sendParamsAsFormData is specified.
sendThisContentType
By default, RESTCaller sends the operation bodyXML data argument as XML with the contentType value set to application/xml. If the sendAsJSON option is true, the contentType value application/json is sent. If the service or resource requires a particular contentType value other than these defaults, use this option to instruct the RESTCaller to send the specified value for the contentType instead.

The working data variable that is mapped to bodyXML must be constructed according to certain rules in order to use this option. For more information, refer to Constructing Working Data XML to Map to JSON.
authorizationType
By default, RESTCaller does not attempt any authorization with the service or resource that is called. Several methods of authorization are supported, and this option must be set to enable the desired method. In addition, the appropriate fields of the corresponding httpAuthorization option must be filled in as described.

The possible values include:
- BASIC – HTTP Basic authorization is attempted. You must provide the httpAuthorization argument.
- NONE – The default. No authorization is attempted.
- NTLM – Authorization using Windows credentials. You must provide the httpAuthorization argument, and then specify the username, password, and domain.
- SBMTOKEN – Forwards the implicit SBM SAML token to the service or resource. This option primarily enables RESTCaller to invoke REST services that are provided by SBM.
- ENDPOINT – Indicates that the authentication information is provided by a custom endpoint. The custom endpoint fields must be mapped to the httpAuthorization argument.
httpAuthorization
Enter the required information as follows:
- If the authorizationType argument is set to BASIC, the basic element of httpAuthorization must have values for username and password. These values are used to complete the HTTP Basic authorization header, which takes the form:
```
Authorization: Basic <base64encoded representation of the string username:password>
```
- If the authorizationType argument is set to NTLM, the ntlm element of httpAuthorization must have values for username, password, and domain.
- If the authorizationType argument is set to ENDPOINT, the endpoint element of httpAuthorization must identify the desired custom endpoint. Map the EndpointID value from the corresponding custom endpoint.
httpHeaders
Enables you to send arbitrary HTTP headers with the REST service request in case the service requires some particular HTTP headers. Note that the HTTP header, “Content-Type” is set implicitly by RESTCaller or via the sendThisContentType option and should not be set via the httpHeaders option.
preserveJSONEscapes
This option preserves JSON escape characters in return values in their JSON-escaped format. By default, JSON escape characters returned by a JSON REST service are converted to the actual character; however, because some characters are invalid in XML, when RESTCaller attempts to convert the JSON result to XML, the call fails if the character is converted to an invalid character in XML. To avoid this issue, use preserveJSONEscapes to preserve the characters in their escaped format.

params

This argument is a list of key-value pairs for query parameters to append to the service or resource URL. The keys and their respective values are appended to the URL after the question mark (?), and are separated by an ampersand (&). For example, given a key (key1) with a value (value1), and another key (key2) with a value (value2), the resulting URL is sent with the request:

http://server:port/service/resource?key1=value1&key2=value2

Tip: You can send empty keys or values if the value should be null or uninitialized. For example:

http://server:port/service/resource?=value1

Or:

http://server:port/service/resource?key1=

However, RESTCaller does not support null key names (values with no preceding key=) like:

http://server:port/service/resource?value1

bodyXML

This argument sets the data for the body of the PUT and POST commands.

If you are sending JSON data, you must instruct RESTCaller to translate the bodyXML to JSON and you must include JsonDoc under the bodyXML. For details, see sendAsJSON.
If you are sending text data, you must instruct RESTCaller to translate the bodyXML to text and you must include TextDoc under the bodyXML. For details, see sendAsText.