Calling RESTful web services
via the Programming API
See also: REST Web Services overview, REST Web Service Resources, REST Web Service Tutorial, 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.
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.
The following four security authentication techniques are supported:
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.
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);