RemoteControl 2 API

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers various API functions.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
 * start a predefined survey (change titles and things)
 * add predefined groups or questions
 * activate the survey, restrict it to start and endtime
 * make it closed,
 * add participant data/tokens when you need them
 * return the unused tokens to the main application
 * get a fieldmap for a survey,
 * invite or remind the participants of your survey

...and much more

Requirements

 * libXML installed

=Setup=

How to configure LSRC2
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to Global settings, choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

Security
LSRC2 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 LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http:////index.php/admin/remotecontrol

LSRC2 fully complies to the XML-RPC specification and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated API Documentation. LSRC2 offers the following functions:

get_session_key
Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

Return on success: (string) session key.

Return on error: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

release_session_key
Using this function you can close a previously opened XML-RPC/JSON-RPC session.

Return: Always 'OK' (string)

List of functions
All functions including descriptions can be found at our developers RemoteControl functions API page.

Also, you can publish your API (check out global settings) and look at it directly.

= Example and helper =

PHP Example
To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the jsonrpcphp Github repository. The library can also get included by composer calling

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

This is an example how to connect to limesurvey:

See a snippet example of list_surveys

JAVA example
To decode and code your json calls you can use the library gson as you can see in the following example:

Python example and glue

 * LimeSurvey API - Python 2 glue
 * LimeSurvey API - Basic client library in Python 3. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

NodeJS example
This script require request, you can include easily with the command

This is a example how to connect to limesurvey:

R example and helper
The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client

C# (Copy & Paste from Forum)
https://www.limesurvey.org/forum/development/99633-c-client-for-ls-remotecontrol2

I have written a small json-rpc client in c#. It is a small one but enough for my purposes. You can use it in your wiki as example or maybe it helps here other people. It is tested and works in my environment but it is possible that i havent found all bugs. You need from nuget package manager Newtonsoft JSON.

RPCclient.cs

programm.cs

= JSON-RPC notes =

The content-type of the HTTP request must be application/json. Most formatting errors are a failure to set the content-type header. This will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.