API

ResourceSpace implements a RESTful API that returns JSON. All requests must be signed using a shared private key specific to each user. This can be performed via GET or POST.

To make an API call simply access the /api/ URL of your ResourceSpace installation with the following parameters:

user The alphanumeric ID of the user to access the system as, for example "admin". Use the function urlencode (or similar) on any usernames that contain special characters such as @ or use the encode value within the string.
function The function you wish to perform. See the API function reference for more details.
param1, param2, param3... The parameters to pass to each function. These are specific to each function and are documented in the function reference. It's important that the values are properly percent-encoded. From version 9.3+ parameters can be passed by name. This will allow requests to miss optional parameters if default is ok. Before version 9.3, if a function had 5 parameters and the developer only needed for example param3, then the request must've been done like "param1=¶m2=¶m3=value3". Use the function urlencode (or similar) on any parameter that contain special characters such as @ | ) or use the encode value within the string.
sign The signature. In order to ensure API requests are not 'tampered with' during transmission we require the caller to build a signature string. This is generated by taking the API key (Session or user) then appending the query URL, and finally producing a sha256 hexadecimal hash of that string.
authmode (v9.5+) The authentication mode. This must be the last parameter passed and can be set to one of the following:-
  • 'userkey' (default) - Use the standard user API key obtained from the user account page in ResourceSpace
  • 'sessionkey' - A session key obtained by calling the API login() function with a username and password
  • 'native' - relies on a cookie obtained by logging in via a browser and pased with the request. Used by client side JavaScript

Examples

This is a GET example in PHP.

// Set the private API key for the user (from the user account page) and the user we're accessing the system as.
$private_key="bfab0581232784c7b04a5c9";
$user="admin";

// Search for 'cat'
$query="user=" . $user . "&function=do_search&search=cat";

// Sign the query using the private key
$sign=hash("sha256",$private_key . $query);

// Make the request and output the JSON results.
echo file_get_contents("https://my.resourcespace.system/api/?" . $query . "&sign=" . $sign);

The equivalent in Perl:

#!/usr/bin/perl -w

use Digest::SHA qw(sha256_hex);
use LWP::Simple;
use Data::Dumper;
use JSON;
use strict;

# Set the private API key for the user (from the user account page) and the user we're accessing the system as.
my $private_key = "bfab0581232784c7b04a5c9";
my $user = "admin";

# Search for 'cat'
my $query = "user=$user&function=do_search&search=cat";

# Sign the query using the private key
my $sign = sha256_hex($private_key . $query);

# Make the request and output the JSON results.
my $result = decode_json(get("https://my.resourcespace.system/api/index.php?$query&sign=$sign"));
print Dumper($result)

This is a POST example in PHP.

// Set the private API key for the user (from the user account page) and the user we're accessing the system as.
$private_key="bfab0581232784c7b04a5c9";
$user="admin";

// Set the URL to point to API.
$url = "https://my.resourcespace.system/api/";

// Formulate the API query data.
$data = array(
    'user'  => $user,
    'function'  => 'do_search',
    'param1'    => 'test',
    'param2'    => '1,2',
    'param3'    => 'date',
    'param4'    => '0',
    'param5'    => '4',
    'param6'    => ''
    );

$query = http_build_query($data);

// Sign the query using the private key.
$sign=hash("sha256",$private_key . $query);

// This part simply replicates the GET query string to be POSTed as a single 'query' POST item.
$data['sign'] = $sign;
$postdata = array();
$postdata['query'] = http_build_query($data);;
$postdata['sign'] = $sign;
$postdata['user'] = $user;

$curl = curl_init($url);
curl_setopt( $curl, CURLOPT_HEADER, "Content-Type:application/x-www-form-urlencoded" );
curl_setopt( $curl, CURLOPT_POST, 1);
curl_setopt( $curl, CURLOPT_POSTFIELDS, $postdata);
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );

// Make the request and output the results.
$curl_response = curl_exec($curl);
print_r(json_decode($curl_response));

This is an example of using GET to obtain a session API key in PHP. (version 9.5+)

// Set the username and password
$username="auser1";
$password="mypassword";

// Set the query to call the login() function, passing in the username and password.
$query="function=login&username=" . $username . "&password=" . $password;

// Make the request and output the session API Key. There is no need to sign as we don't have a key yet.
echo file_get_contents("https://my.resourcespace.system/api/?" . $query);

Other languages are possible and would work in a similar way.

API test tool

api_test_tool

The API test tool (Admin -> System -> API test tool) allows you to try out commands directly in the ResourceSpace interface prior to inclusion in your development environment.

Simply select the function then enter the parameters as defined in the API documentation. The JSON output is displayed below.

From version 9.6+ any optional arguments must be actively enabled in order to be applied when submitting the request.