REST API

TODO

Under development

Available from version x (LS 5.5.0?)

Available API endpoints

Technical specification. UML.

Introduction

LimeSurvey REST API v1 is available in LS 5.5.0 or more recent which offers various API endpoints.

Setup

Configure

In order to use REST API you must first enable the service, and then adjust the settings to suit your needs. To enable login to the LimeSurvey administration, go to Global settings, choose the tab 'Interfaces' and select 'Publish API on /rest'.

Security

The REST API uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also the REST API is protected against brute-force password cracking - like the normal administration login.

Usage

Documentation

The available API endpoints are fully documented using swagger https://api.limesurvey.org/swagger.

API Location

The REST API URL is http://www.yourdomain.com/rest/v1 .

Authorisation

Currently the REST API supports server side session authorisation. You use your standard admin username and password to gain API authorisation.

Login

To login to the REST API, perform a POST request to /rest/v1/session with 'username' and 'password' post data. The API will returns a 200 response with a session id string body.

Bearer Authentication

The session id string returned by /rest/v1/session can be used as authorisation in requests to other endpoints using bearer authentication (also called token authentication).

Set HTTP header 'Authorization' with the value 'Bearer my-session-id-string-returned-from-server' in each request endpoints that require authorisation.

Logout

To logout of the REST API perform an authorised DELETE request to the /rest/v1/session.

Endpoints

See the Swagger Documentation for full details.

/rest/v1/

session

session

siteSettings

siteSettings/<setting-name>

survey

survey/<id>

questionGroup/<surveyId>

questionGroup

questionGroup/<groupId>

questionGroupProperties/<groupId>

questioGroupProperties/<groupId>

Examples

PHP Example

composer require guzzlehttp/guzzle:^7.0

or by inclusion of the following lines in your composer.json file:

{
    "require": {
        "guzzlehttp/guzzle": "^7.0"
    }
}

This is an example how to connect to limesurvey REST API:

<?php

$baseUrl = 'https://www.mysurveysite.com/';
$api = 'rest/v1/';
$apiUrl = $baseUrl . $api;
$timeout = 5;

// Login
$loginClient = new GuzzleHttp\Client([
    'base_uri' => $apiUrl,
    'timeout'  => $timeout
]);

$loginResult = $loginClient->request('POST', 'session', [
    'username' => 'admin',
    'password' => 'password',
]);
$sessionId = null;
if ($loginResult->getStatusCode() == 200) {
    $sessionId = $loginResult->getBody();
}else {
    throw new Exception('Login failed: ' . $res->getStatusCode());
}

// Use session id string to make authorised requests
$client = new GuzzleHttp\Client([
    'base_uri' => $apiUrl,
    'timeout'  => $timeout,
    'headers'  => ['Authorization' => 'Bearer ' . $sessionId]
]);

$result = $client->request('POST', 'siteSettings/sitename');
$siteName = null;
if ($loginResult->getStatusCode() == 200) {
    $siteName = $loginResult->getBody();
} else {
    throw new Exception('Failed getting site name: ' . $res->getStatusCode());
}

$result = $client->request('DELETE', 'session');