Calling RESTful web services via the Programming API

Documentation home

Getting Started. 1

Adding Security. 1

Example. 2

See also: REST Web Services overview, REST Web Service Resources, Using OAuth Security

This document provides information and examples on calling a RESTful web service using the programming API; this is only available from Javascript scripts. Before getting started, you should check the available documentation provided for the RESTful web service that you are calling: there are a variety of techniques used for passing and returning data, security options etc and this information should be documented by the provider.

Getting Started

Most of the REST functionality is provided via the RestServices API class which is accessed via the services object from a Javascript script:

services.rest.

Enter this in the script editor (including the final “.”) and you should see a list of the available methods and associated documentation for each method. Here is a simple example of calling a web service that returns a JSON object:

var response = services.rest.get("http://example.com/rest/users");
if (response.isSuccess())
{
 var results = JSON.parse(response.getBody());
 ..
}
 

In this example, we are calling the web service’s get method. Other methods e.g. post, put, patch, delete etc are also available.

The response object provides access to all aspects of the response which includes: the response body, headers, http status code, success/failure indicator. To see the response object documentation, enter “response.” after the first line of code above or click the link at the start of this paragraph.

Adding Security

The following four security authentication techniques are supported:

• Basic Authentication
• Digest Authentication
• NTLM Authentication
• OAuth Authentication

The first three of these are different implementations of a userid/password specification. OAuth Authentication is more complex, follow the link for configuration details and examples.

Example

Spotify search, request details passed as request parameters, returns a JSON string, no security

var result;

var searchQuery = fields.search.value;

var params = {type: "artist ", q: searchQuery};

var response;

try

{

response = services.rest.get("https://api.spotify.com/v1/search ", null, params);

}

catch (e)

{

// catch connection or configuration failure

event.owner.addErrorMessage(e);

}

if (response.isSuccess())

{

result = JSON.parse(response.body);

}

else

{

event.owner.addErrorMessage("Error: " + response.code + " - " + response.body);

}

// process the response, add artists to table

var artists = result.artists.items;

for (var artist in artists)

{

tables.spotifyResults.insertRow();

tables.spotifyResults.name.value = artist.name;

}

tables.spotifyResults.setCurrentRow(0);