Built-in Inbound REST Interface

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. The following tables list the built-in services that are available, the examples below use the cURL command to illustrate the usage of each service.

Note: RunMyJobs also offers the Inbound REST Extension, which lets you use API key authentication.

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.2.0-2023-07-27-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 APIs
• Inbound REST Extension