How to implement a client for REST web services

Scope

Jobs can be implemented to access RESTful web services.
A REST web service client is available for Scripting of Jobs and Monitors that are implemented with Java or JavaScript.
This feature is provided with JITL-213 - Getting issue details... STATUS
POST and PUT with a body is provided with JITL-273 - Getting issue details... STATUS

Implementation

JITL provides a static Java class that can be used with Java and JavaScript. This class accepts a URL and returns an object in JSON syntax.
For use with JavaScript the JSON object can be converted to a JavaScript object.

Methods

Method	Arguments	Description
com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService		execute a GET operation and return the result object
	url	a URL that includes host and port of the web service, e.g. http://localhost:44445/jobscheduler/agent/api/
com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand		execute a configurable operation and return the result object
	operation	one of the HTTP verbs: `GET, POST, PUT, DELETE` POST\|PUT can be parameterized with the body `POST(<person><id>4711</id><name>helloworld</name></person>)`
	url	a URL that includes host and port of the web service, e.g. http://localhost:44445/jobscheduler/agent/api/
com.sos.jitl.restclient.JobSchedulerRestClient.getRestService		execute the web service operation using GET
	host	hostname or ip address of the web service, e.g. `localhost`
	port	port for which the web service is accessible, e.g. 4445
	path	path and query string of the web service URL, e.g. `/jobscheduler/agent/api/`
	protocol	protocol in use including `http, https`
com.sos.jitl.restclient.JobSchedulerRestClient.postRestService		execute the web service operation using POST
	host	hostname or ip address of the web service, e.g. `localhost`
	port	port for which the web service is accessible, e.g. 4445
	path	path and query string of the web service URL, e.g. `/jobscheduler/agent/api/`
	body	The body for the post

Adding Header items

The header "Accept=application/json" will automatically be added.
You can add header items with
- com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("header","value");

Integration with JavaScript

Basically a web service call is implemented by executing one of the above methods from the JITL Java class, e.g.:
- var response = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://localhost:44445/jobscheduler/agent/api/" );
- var response = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand( "get", "http://localhost:44445/jobscheduler/agent/api/" );
Webservice returns a serialized JSON Object
- The result object returned by the web service can be converted to a JavaScript JSON object by use of the eval() function:
  - eval ( "var jsonObject = " + response + ";" );
- Properties of the JSON object can be accessed within the object hierarchy provided by the web service result object like this:
  - jsonObject.system.hostname
Webservice returns a xml element
- The result can be parsed using SOSXMLXPath
  - see example below

function spooler_process() { 
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/18/" );
  spooler_log.info( s);
  var xmlDOM = new Packages.sos.xml.SOSXMLXPath( new java.lang.StringBuffer( s ) );
   spooler_log.info( "Firstname is " + xmlDOM.selectSingleNodeValue( "//CUSTOMER/FIRSTNAME" ));
 
  return false;
}

Example

JavaScript example for use with a job: this job requests the status information from the JobScheduler Universal Agent and returns the total number of tasks that have been executed during the Agents' lifetime. This job reads the web service URL from a job parameter.
Download: rest_client.job.xml

Job rest_client

<job  stop_on_error="no" >
    <params >
        <param  name="agent_service" value="localhost:4445/jobscheduler/agent/api/"/>
    </params>

    <script  language="java:javascript">
        <![CDATA[
function spooler_process() {

    var parameters = spooler.create_variable_set();
    parameters.merge( spooler_task.params );

    var agent_service = parameters.value( "agent_service" );
    var response = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( agent_service );

//  alternative REST methods
//  var response = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://localhost:44445/jobscheduler/agent/api/" );
//  var response = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand("get", "http://localhost:4445/jobscheduler/agent/api/" );
//  var response = com.sos.jitl.restclient.JobSchedulerRestClient.getRestService( "localhost", 4445, "/jobscheduler/agent/api/", "http" );

    if (response) {
        eval ( "var jsonObject = " + response + ";" ); 
        spooler_log.info( jsonObject.totalTaskCount + " tasks on Agent [" + agent_service + "]: " + jsonObject.system.hostname );
    } else {
        spooler_log.error( "no response from Agent web service at: " + agent_service );
    }

    return (response != "");
}
        ]]>
    </script>

    <run_time />
</job>

Full Example with GET|POST|PUT|DELETE and XML Responses

function spooler_process() { 
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/18/" );
  spooler_log.info( s);
  var xmlDOM = new Packages.sos.xml.SOSXMLXPath( new java.lang.StringBuffer( s ) );
  spooler_log.info( "Firstname is " + xmlDOM.selectSingleNodeValue( "//CUSTOMER/FIRSTNAME" ));

//Creating a person with post
  com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("Content-Type", "application/xml");
  var post = "post(<resource><ID>4711</ID><LASTNAME>world</LASTNAME><FIRSTNAME>Hello</FIRSTNAME></resource>)";
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand(post, "http://www.thomas-bayer.com/sqlrest/CUSTOMER/" );

//Reading the new entry
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );
  var xmlDOM = new Packages.sos.xml.SOSXMLXPath( new java.lang.StringBuffer( s ) );
  spooler_log.info( "Name is " + xmlDOM.selectSingleNodeValue( "//CUSTOMER/FIRSTNAME" ) + " " +  xmlDOM.selectSingleNodeValue( "//CUSTOMER/LASTNAME" ));

//Changing the name
  com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("Content-Type", "application/xml");
  var post = "post(<resource><FIRSTNAME>Uwe</FIRSTNAME></resource>)";
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand(post, "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );

//Reading the name
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/18/" );
  var xmlDOM = new Packages.sos.xml.SOSXMLXPath( new java.lang.StringBuffer( s ) );
  spooler_log.info( "Firstname is " + xmlDOM.selectSingleNodeValue( "//CUSTOMER/FIRSTNAME" ));
 

//Deleting the new entry
  com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("Content-Type", "application/xml");
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand("delete", "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );

//Reading the deleted entry
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );
  spooler_log.info( s);

//Creating a person with put
  com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("Content-Type", "application/xml");
  var put = "put(<resource><LASTNAME>world</LASTNAME><FIRSTNAME>Hello</FIRSTNAME></resource>)";
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand(put, "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711" );

//Reading the new entry
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );
  var xmlDOM = new Packages.sos.xml.SOSXMLXPath( new java.lang.StringBuffer( s ) );
  spooler_log.info( "Name is " + xmlDOM.selectSingleNodeValue( "//CUSTOMER/FIRSTNAME" ) + " " +  xmlDOM.selectSingleNodeValue( "//CUSTOMER/LASTNAME" ));

//Deleting the new entry
  com.sos.jitl.restclient.JobSchedulerRestClient.headers.put("Content-Type", "application/xml");
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestServiceCommand("delete", "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );

//Reading the deleted entry
  var s = com.sos.jitl.restclient.JobSchedulerRestClient.executeRestService( "http://www.thomas-bayer.com/sqlrest/CUSTOMER/4711/" );
  spooler_log.info( s);
  return false;
}

References

Change Management References

T	Key	Linked Issues	Fix Version/s	Status	P	Summary	Updated

Loading...

Refresh

Documentation

R EST (Representational State Transfer)

Space shortcuts

Page tree

Scope

Implementation

Methods

Adding Header items

Integration with JavaScript

Example

Full Example with GET|POST|PUT|DELETE and XML Responses

References

Change Management References

Documentation