$Rest Methods

Overview

Allows to call rest services with JSON or XML content types.

Rest service operations consist of objects Client and Request and Response.

Rest Service Calling Walkthrough

Creating Rest Client

To create a client use $Rest.Create method by providing the rest service base url.

var client = $Rest.Create('http://api.geonames.org/');

Some of rest services may require the authentication. Workrunner supports the OpenAuth2 based authentication services and to create a authenticated client please specify the service and identity as below;

var client = $Rest.Create('https://graph.microsoft.com/v1.0/', 'Office365', '', $WorkItem.CompletedBy).EnsureAuthenticated();

This method acquires a authentication token from service and ensures client is authenticated. If token cannot be acquired from service EnsureAuthenticated method throws a javascript exception. You can also use IsAuthenticated property and Authenticate method to perform same operation without error handling.

Creating Rest Request

After creating client connection you can create rest request and populate parameters as below;

var request = client.Request('childrenJSON')
                .AddQueryParameter('username', 'demo')
                .AddQueryParameter('geonameId', id);

You may also set http headers with AddHeader method.

Some rest methods requires JSON or XML based body and you can specify the content of request with AddObject or AddXml methods.

Fetching Rest Response

After Request populated you can call the Execute method to execute and fetch Response object. Execute method by default does not perform any error check. If you want to be sure request has successfully executed please use Expect method to specify expected status code.

var response = request.Execute();

if (response.StatusCode == "OK") {
    var val = response.GetHeader('X-Header');
    var obj = response.ToJson();
}

You can also use Get, Delete, Put, Post, Patch methods to call service with corresponding method or you can manually set the RestRequest.Method before executing.

If service always returns JSON or XML you can use ExecuteJson or ExecuteXml method to fetch response as JSON object or XML navigator.

var object = request.ExecuteJson();

// object.person.name;