Calling REST Services from within Redwood Server

The HTTP process definition type allows you to call REST services.

Built-in Parameters

• HTTP_URL - The URL of the REST service.
• HTTP_Method - The HTTP method used to call the REST server; defaults to GET when this parameter is missing.
• HTTP_Version - The HTTP version to use for the request.
• HTTP_Content-Type - The Content-Type header to set for the request.

Out and In/Out Parameters

Out and In/Out parameters are set automatically when XML or JSON data is returned by the server and the parameter name matches an element in the data. If the parameter is of type Array, matches the name of a JSON array in the data returned by the server, then the array will be filled with the values. The default JSONPath used is $..<fieldname> where <fieldname> is taken from the parameter name, you specify your custom JSONPath in the Process Format field of the parameter.

Syntax

<text>
[headers]
Content-Type=application/json

• <text> - (optional) Data to send to the server
• [headers] - List of headers with the syntax <header_name>=<header_value>

Multipart/form-data Syntax

--<boundary>
 Content-Disposition: form-data; name="<name>" [filename="<name>"]
 Content-Type: <content-mime-type-1>[;<content-encoding-1>]
<data-1>
[--<boundary>--
 Content-Disposition: form-data; name="<name>" [filename="<name>"]
 Content-Type: <content-mime-type-n>[;<content-encoding-n>]
<data-n>
<boundary>--]+
[Headers]
Content-Type=multipart/form-data; boundary=<boundary>

• <boundary> - The boundary delimiter cannot appear inside any of the encapsulated parts, you may have to enclose the "boundary" parameter values in quotes in the Content-Type header field.
• <name> - The name of the content should be unique, you should avoid parts with the same name.
• filename="<name> - Optional file name, if the content is to be used as a file.
• <content-mime-type-n>[;<content-encoding-n>] - MIME type and, optionally, encoding of the part.
• <data-n> - Data must be of the media type specified in the Content-Type declaration for the part (MIME type and, if specified, the encoding).
• [ .. ]+ - There can be more than two parts, each must have its unique name and the correct Content-Type header for the data.

Parameter Substitution

Syntax

${parameter[:<encoding>]}

The following parameter escape and encoding strategies are available:

• xml - escape using XML 1.1 character escaping rules, the result will also use character entities for any non-ASCII character
• json - escape the parameter so that it can be included inside of a JSON string
• url - escape using URL escaping, assuming a UTF-8 character set
• html - escape using HTML character escaping rules
• base64 - encode using base64

These can also be combined to allow multiple escapes to be applied in order. If the value of the parameter is null or empty, then nothing will be substituted, and if the expansion refers a parameter that doesn't exist, this will be left in the source, for example, ${ParamThatDoesntExist} will get left in the Source field.

Example

A parameter GREETING is set to &greeting="Hello World"

X-My-Token=${GREETING} is evaluated as &greeting="Hello World"
X-My-Token0=${GREETING:url} is evaluated as %26greeting%3d%22Hello%20World%22
X-My-Token1=${GREETING:xml} is evaluated as &greeting="Hello World"
X-My-Token2=${GREETING:json} is evaluated as &greeting=\"Hello World\"
X-My-Token3=${GREETING:html} is evaluated as &greeting="Hello World"
X-My-Token3=${GREETING:base64} is evaluated as JmdyZWV0aW5nPSJIZWxsbyBXb3JsZCI=

Credentials

You use credentials of protocol SOAP with the outgoing REST API; the endpoint must match the server's hostname and optionally port (<server_name>[:<port>]), the process server will first search for a credential with the port and hostname provided in the HTTP_URL parameter, then fall back to the hostname.

Procedure

1. Navigate to Definitions > Processes.
2. From the context-menu, choose New Process Definition, select REST/HTTP.
3. Fill the Name field.
4. Fill the Source field (optional).
5. On the Parameters tab, you fill the HTTP_URL and HTTP_Method parameters.
6. Choose Save & Close.

Example

Redwood REST API Example

You wish to close a queue in a remote Redwood Server central server using the REST API.

1. Navigate to Definitions > Processes.
2. From the context-menu, choose New Process Definition, select REST/HTTP.
3. You fill REST_Redwood_Example in the Name field.
4. You fill the below text in the Source field.
5. On the Parameters tab, you set HTTP_URL to https://redwood.example.com/redwood/api-rest/xml.
6. On the Parameters tab, you set HTTP_Method to PUT.
7. On the Parameters tab, you create a parameter named Held with Simple Constraint Type set to List and Simple Constraint Data set to true,false.

<?xml version='1.0'?>
<Queue>
  <Comment />
  <Description>Queue for REST API</Description>
  <Name>REST_Queue</Name>
  <Partition type="Partition" path="GLOBAL" />
  <ParentApplication />
  <ExecutionSize />
  <Held>${Held}</Held>
  <HoldLevel />
  <Inclusive>false</Inclusive>
  <InclusiveConsoleJobs>true</InclusiveConsoleJobs>
  <Overdue>false</Overdue>
  <QueueTimeZone />
  <TimeWindow />
</Queue>
[Headers]
Authorization=Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg

Jira Example

You want to update an issue in Atlassian Jira, your issue tracking system.

1. Navigate to Security > Credentials.
2. Choose New Credential from the context-menu.
3. Select soap as credential protocol.
4. Fill the username into the Real User field, the password into the Password field, repeat.
5. Fill jira.example.com into the Endpoint field.
6. Navigate to Definitions > Processes.
7. From the context-menu, choose New Process Definition, select REST/HTTP.
8. Fill REST_Jira_Example in the Name field.
9. Fill the below text in the Source field.
10. Fill the Real User as specified in your credential in the Run As User field.
11. On the Parameters tab, you set HTTP_URL to https://jira.example.com/rest/api/2/issue/QA-31.
12. On the Parameters tab, you set HTTP_Method to PUT.
13. Choose Save & Close.
14. Locate the newly created process definition and select Submit from its context-menu.
15. Select Next then Submit.

{
   "update": {
   "description": [
         {
            "set": "JIRA should also come with a free pony"
         }
      ],
      "comment": [
         {
            "add": {
               "body": "This request was originally written in French, which most of our developers can't read"
            }
         }
      ]
   }
}
[Headers]
Content-Type=application/json

Bearer Authentication Example

You have been issued a bearer token to connect to a REST service.

1. Navigate to Definitions > Processes.
2. From the context-menu, choose New Process Definition, select REST/HTTP.
3. You fill REST_Example_Bearer in the Name field.
4. You fill the below text in the Source field.
5. On the Parameters tab, you set HTTP_URL to https://rest.example.com/rest/api/some/service?q="hello world!".
6. On the Parameters tab, you set HTTP_Method to GET.
7. Choose Save & Close.
8. Locate the newly created process definition and select Submit from its context-menu.
9. Select Next then Submit.

[Headers]
Authorization=Bearer AAAAAAAAAAAAAAAAAAAAAGlHGAEAAAAAV2h5I%3GFyZSB5b3Ugd2Fzd
Content-Type=application/x-www-form-urlencoded

Multipart

The following is a multipart form data request consisting of a JSON document and an XML document. The A300B4a350xw is a boundary marker that can be freely chosen but that should not be present in the data, in this example the JSON or XML you send.

--A300B4a350xw
 Content-Disposition: form-data; name="jsondata"
 Content-Type: application/json; charset=UTF-8
{
  "Name" : [
    "John",
    "Joe" : "apple",
    "Pete" : "orange"
  ]
}
--A300B4a350xw--
 Content-Disposition: form-data; name="xmldata"
 Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<xml id="test" version="1.0">
  <content>
    <empty ref="simple" />
    <child>
      <plan partitions="3" />
    </child>
  </content>
</xml>
A300B4a350xw--
[Headers]
Content-Type=multipart/form-data; boundary=A300B4a350xw

See Also

• Credentials
• Integrating Redwood Server with REST API's

webservice