Connecting REST Services with Redwood Server

The inbound REST interface allows you to to use webhooks from third party services to integrate with the automation solution. The service requires you log on using basic authentication, such as an Authorization header, if you require API key authentication, use the REST component instead. The following tables list the builtin services that are available, the examples below use the cURL command to illustrate the usage of each service.

Name	Method	Path	Description	Output
jobfile	GET	api-rest/jobfile/	Retrieves the JobFile with the specified unique id	JobFile contents
capabilitiesxml	GET	api-rest/capabilitiesxml	Retrieves the WADL for the REST API	test/xml
version	GET	api-rest/version	Retrieves the version of Redwood Server	test/xml
api-libs	GET	api-rest/api-libs	Retrieves all JAR libraries	application/zip
object	GET	api-rest/object/{objectType}/{businessKey}	Retrieves the specified object as XML	text/xml
car	GET	api-rest/car/{carType}/{businessKey}	Retrieves the specified object as a CAR file	application/zip
car-put	PUT	api-rest/car	Sends a CAR file to the promotion module	text/xml
jar-put	PUT	api-rest/jar	Sends a JAR file to the promotion module	text/xml
xml-put	PUT	api-rest/xml	Sends an object in the form of XML	text/xml
list	GET	api-rest/list/{objectType}	Retrieves a list of objects the of the specified type	text/xml
list-scripts	GET	api-rest/scripts-list	Retrieves a list of all libraries and custom RedwoodScript process definitions	text/xml
get-scripts	POST	api-rest/scripts-get	Retrieves a list of all libraries and custom RedwoodScript process definitions in a CAR file	application/zip

note

Windows 10 ships with curl.exe; it is very important to specify the exe extension in Powershell as curl is an alias for Invoke-WebRequest.

note

Some long examples have been split across multiple lines, lines ending with a backslash \ are meant to be issued on one line (without the backslash).

Syntax

The REST API uses the following syntax:

http[s]://<server>[:<port>]/<context>/api-rest/<service>[[/<parameters>]*[?<parameter1>[&<parameter2>]*]]

• <server> - The hostname of the central Redwood server.
• <port> - (optinal) The port of the server.
• <context> - The context part of the URL.
• /<parameters> - Path parameters (depending on service).
• ?<parameter1> and &<parameter2> - Query parameters.

Services

jobfile

The jobfile REST service allows you to retrieve an output or log file from an process by uniqueId of the JobFile.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/jobfile/<uniqueId>

• <uniqueId> - The uniqueId of the JobFile to retrieve,

Example

Contents of getJobFile.sh:

#!/bin/sh

function _usage(msg)
{
  echo $msg
  echo "Usage: $0 <JobFile_UniqueId>
  <JobFile_UniqueId> must be a positive integer."
}

if [ -z "$1" ]
then
 _usage();
  exit 123;
elif ! [ $1 -eq $1 ] 2>/dev/null
then
 _usage;
  exit 124;
elif [ $1 -lt 0 ]
then
 _usage;
  exit 125;
fi

#Set Environment
#ENDPOINT="https://server.example.com/redwood/api-rest/jobfile/$1"

read -s -p "Enter Username: " user
echo ""
read -s -p "Enter Password: " passwd
echo ""

#Call the service
USERPASSWD=`jecho -base64  $user:$passwd`

curl -H "Authorization: Basic $USERPASSWD" -H "Content-Type: application/xml; charset=utf-8" -X GET ${ENDPOINT} --output report.txt

capabilitiesxml

The capabilitiesxml service serves an XML file with the supported services.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/capabilitiesxml

Example

$ curl -H "Authorization: Basic $USERPASSWD" -X GET http://server.example.com/redwood/api-rest/capabilitiesxml --output wadl.xml

version

The version service provides the version of Redwood Server.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/version

Example

$ curl -X GET http://server.example.com/redwood/api-rest/version

Result

2023.3.0.0-2023-11-16-2359_999999999999

api-libs

The api-libs service provides a ZIP file containing all custom libraries.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/api-libs

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X GET \
https://server.example.com/redwood/api-rest/api-libs --output out.zip

object

The object service retrieves the XML representation of an object.

note

Object type, partition, and object names are case sensitive.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/object/<object_type>/<partition>.<object_name>

• <object_type> - The type of object you wish to retrieve (technical name), such as TimeWindow, ProcessServer, or Queue.
• <partition> - The partition of the object to retrieve.
• <object_name> - The name of the object to retrieve.

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X GET \
https://server.example.com/redwood/api-rest/object/JobDefinition/GLOBAL.RS_Test --output rs_test.xml

car

The car service retrieves the CAR file with the requested object.

note

Object type, partition, and object names are case sensitive.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/car/<object_type>/<partition>.<object_name>

• <object_type> - The type of object you wish to retrieve (technical name), such as TimeWindow, ProcessServer, or Queue.
• <partition> - The partition of the object to retrieve.
• <object_name> - The name of the object to retrieve.

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X GET \
https://server.example.com/redwood/api-rest/car/JobDefinition/GLOBAL.RS_Test --output rs_test.car

car-put

The car-put service allows you to import a CAR file.

Syntax

PUT http[s]://<server>[:<port>]/<context>/api-rest/car/

Request Header

• async - Asynchronous upload, accepts true and false (default).
• X-Redwood-Description - Description for the import.
• X-Redwood-Ruleset - Import rule set (<partition>.<name>) to use for the import.
• X-Redwood-Ruleset-Properties - Import rule set parameter-value pairs ([<parameter1>=<value1>[,<parameter2>=<value2>]*]).
• X-Redwood-TargetPartition - Target partition to import the objects into.
• X-Redwood-Signed-Car - Signed CAR files must have this header set to true, false is the default.
• X-Redwood-FileName - Name of the CAR file in the import process; defaults to carin.car.

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "X-Redwood-Description: Import from curl." \
-H "X-Redwood-Ruleset: GLOBAL.MyIRS" -H "X-Redwood-Ruleset-Properties: sapSys=N00" -H "X-Redwood-TargetPartition: MyPartition" \
-H "X-Redwood-Signed-Car: false" -H "X-Redwood-FileName: Karin" -X PUT https://server.example.com/redwood/api-rest/car \
--data-binary /redwood/my_objects.car

jar-put

The jar-put service allows you to upload a JAR file to a library.

Syntax

PUT http[s]://<server>[:<port>]/<context>/api-rest/jar/

Request Headers

• async - Asynchronous upload, accepts true and false (default).
• X-Redwood-Library - The <partition>.<name> of the library to use.
• X-Redwood-FileName - The name the JAR file should have in the library.

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "X-Redwood-Library: GLOBAL.Custom_DB" \
-H "X-Redwood-FileName: mssql" -H "Content-Type: application/xml; charset=utf-8" -X PUT \
https://server.example.com/redwood/api-rest/jar --data-binary /redwood/mssql-jdbc-8.2.0.jre11.jar

Result

<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>
<message>
  <message-options>
    <persist>N</persist>
  </message-options>
<rest-import-job><job-id>471</job-id><status>Completed</status></rest-import-job>
</message>

xml-put

The xml-put service allows you to upload an XML representation of an object, allowing you to alter it.

Syntax

PUT http[s]://<:%s/\s\+$//eserver>[:<port>]/<context>/api-rest/xml/

Example

The following script illustrates how to control a queue by sending XML to the remote central Redwood server.

Contents of manageQueue.sh:

#!/bin/sh

held=$(echo "$1" | awk '{print tolower($0)}')

case $held in
  "true" | "false")
    break;
    ;;
    *)
    echo "Hold state of queue can only be 'true' (queue must be held) or 'false' (queue must not be held).";
    exit 123;
    ;;
esac

#Set Environment
ENDPOINT="https://server.example.com/redwood/api-rest/xml"

read -s -p "Enter Username: " user
echo ""
read -s -p "Enter Password: " passwd
echo ""

#Call the web service
USERPASSWD=`jecho -base64  $user:$passwd`

curl -H "Authorization: Basic $USERPASSWD" -H "Content-Type: application/xml; charset=utf-8" -X PUT ${ENDPOINT} --data @- <<EOF
<?xml version='1.0'?>
<Queue>
  <Comment />
  <Description />
  <Name>RestAPIQueue</Name>
  <Partition type="Partition" path="GLOBAL" />
  <ParentApplication />
  <ExecutionSize />
  <Held>"${1}"</Held>
  <HoldLevel />
  <Inclusive>false</Inclusive>
  <InclusiveConsoleJobs>true</InclusiveConsoleJobs>
  <Overdue>true</Overdue>
  <QueueTimeZone />
  <TimeWindow />
</Queue>
EOF

Result

The command $ manageQueue.sh true returned the following:

Enter Username:
Enter Password:
<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>
<message>
  <message-options>
    <persist>N</persist>
  </message-options>
  <rest-object>
    <business-key>Queue:GLOBAL.RestAPIQueue</business-key>
    <url>/example/api-rest/object/Queue/GLOBAL.RestAPIQueue</url>
    <description></description>
  </rest-object>
</message>

list

The list service allows you to search for objects of a specified type.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/list/<object_type>?stylesheet=<true|false>&search=<query>&check=<export|none>

• stylesheet - Allows you to request the default REST stylesheet doc:/<partition>/REST/Default_StyleSheet.xml; accepts values true or false
• search - Case-insensitive search query
• check - Accepts values export and none; export list only exportable definitions such as a master JobDefinition and not all its branches.

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X GET \
http://server.example.com/redwood/api-rest/list/JobDefinition?stylesheet=false&search=RS&check=export

scripts-list

The scripts-list service provides a list of all custom process definitions and libraries.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/scripts-list

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X GET \
http://server.example.com/redwood/api-rest/scripts-list

get-scripts

The get-scripts service provides a CAR file containing all custom process definitions and libraries.

Syntax

GET http[s]://<server>[:<port>]/<context>/api-rest/scripts-get

Example

$ curl -H "Authorization: Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg" -H "Content-Type: application/xml; charset=utf-8" -X POST \
http://server.example.com/redwood/api-rest/scripts-get --output scripts.car

See Also

• Integrating Redwood Server with REST API's
• REST Component

rest restful