REST API - Revision history

Kfoster: Replaced content with "; TODO - Under development : Available from version x (Version to be defined)"

2023-10-30T15:40:56Z

Replaced content with "; TODO - Under development : Available from version x (Version to be defined)"

Holch at 14:59, 3 May 2023

2023-05-03T14:59:35Z

← Older revision		Revision as of 16:59, 3 May 2023
Line 1:		Line 1:
	; TODO - Under development		; TODO - Under development
	: Available from version x (~~LS 5.5.0?~~)		: Available from version x (Version to be defined)
	: Technical specification. UML.		: Technical specification. UML.

	=Introduction=		=Introduction=

	LimeSurvey REST API (v1) is available from ~~LS 5.5.0~~ and offers '''various [https://api.limesurvey.org/swagger API endpoints]'''. The initial v1 REST API provides a subset of the functionality provided by the existing [https://manual.limesurvey.org/RemoteControl_2_API Remote Control API] except via a REST interface rather than an RPC interface.		LimeSurvey REST API (v1) is available from Version [TBD] and offers '''various [https://api.limesurvey.org/swagger API endpoints]'''. The initial v1 REST API provides a subset of the functionality provided by the existing [https://manual.limesurvey.org/RemoteControl_2_API Remote Control API] except via a REST interface rather than an RPC interface.

	=Setup=		=Setup=

Kfoster: /* PHP Example */

2022-10-20T15:27:37Z

PHP Example

← Older revision		Revision as of 17:27, 20 October 2022
Line 82:		Line 82:
	<source lang="php">		<source lang="php">
	<?php		<?php

	require './vendor/autoload.php';		require './vendor/autoload.php';

Line 137:		Line 136:
	echo 'Site name: ' . $siteName;		echo 'Site name: ' . $siteName;


			///////////////////////////////////////////////////////////////////////////////
	// Logout		// Logout
			// - This is important. If you create too many simultaneous login session
			// - you may be temporarily blocked from creating more.
	$result = $client->request('DELETE', 'session');		$result = $client->request('DELETE', 'session');
	</source>		</source>

Kfoster: /* PHP Example */

2022-10-20T15:25:47Z

PHP Example

← Older revision		Revision as of 17:25, 20 October 2022
Line 83:		Line 83:
	<?php		<?php

	$baseUrl = 'https://www.mysurveysite.com/';		require './vendor/autoload.php';

			use GuzzleHttp\Client;

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

			///////////////////////////////////////////////////////////////////////////////
	// Login		// Login
	$loginClient = new ~~GuzzleHttp\~~Client([
			$loginClient = new Client([
	'base_uri' => $apiUrl,		'base_uri' => $apiUrl,
	'timeout' => $timeout		'timeout' => $timeout
Line 95:		Line 101:

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

	// Use session id ~~string to make authorised requests~~		///////////////////////////////////////////////////////////////////////////////
	$client = new ~~GuzzleHttp\~~Client([		// Use the API with session id that we got from login
			$client = new Client([
	'base_uri' => $apiUrl,		'base_uri' => $apiUrl,
	'timeout' => $timeout,		'timeout' => $timeout,
Line 112:		Line 124:
	]);		]);

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

Kfoster: /* PHP Example */

2022-10-20T07:40:38Z

PHP Example

← Older revision		Revision as of 09:40, 20 October 2022
Line 115:		Line 115:
	$siteName = null;		$siteName = null;
	if ($result->getStatusCode() == 200) {		if ($result->getStatusCode() == 200) {
	$siteName = json_decode((string) $~~loginResult~~->getBody(), true);		$siteName = json_decode((string) $result->getBody(), true);
	} else {		} else {
	throw new Exception('Failed getting site name: ' . $result->getStatusCode());		throw new Exception('Failed getting site name: ' . $result->getStatusCode());

Kfoster: /* PHP Example */

2022-10-20T07:40:13Z

PHP Example

← Older revision		Revision as of 09:40, 20 October 2022
Line 101:		Line 101:
	if ($loginResult->getStatusCode() == 200) {		if ($loginResult->getStatusCode() == 200) {
	$sessionId = json_decode((string) $loginResult->getBody(), true);		$sessionId = json_decode((string) $loginResult->getBody(), true);
	}else {		} else {
	throw new Exception('Login failed: ' . $result->getStatusCode());		throw new Exception('Login failed: ' . $result->getStatusCode());
	}		}

Kfoster at 07:38, 20 October 2022

2022-10-20T07:38:56Z

← Older revision		Revision as of 09:38, 20 October 2022
Line 35:		Line 35:

	===Bearer Authentication===		===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).		The session id string returned in the JSON response of ''/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.		Set HTTP header 'Authorization' with the value 'Bearer my-session-id-string-returned-from-server' in each request to endpoints that require authorisation.

	===Logout===		===Logout===
Line 100:		Line 100:
	$sessionId = null;		$sessionId = null;
	if ($loginResult->getStatusCode() == 200) {		if ($loginResult->getStatusCode() == 200) {
	$sessionId = $loginResult->getBody();		$sessionId = json_decode((string) $loginResult->getBody(), true);
	}else {		}else {
	throw new Exception('Login failed: ' . $result->getStatusCode());		throw new Exception('Login failed: ' . $result->getStatusCode());
Line 115:		Line 115:
	$siteName = null;		$siteName = null;
	if ($result->getStatusCode() == 200) {		if ($result->getStatusCode() == 200) {
	$siteName = $~~result~~->getBody();		$siteName = json_decode((string) $loginResult->getBody(), true);
	} else {		} else {
	throw new Exception('Failed getting site name: ' . $result->getStatusCode());		throw new Exception('Failed getting site name: ' . $result->getStatusCode());
	}		}

			echo 'Site name: ' . $siteName;

	// Logout		// Logout
	$result = $client->request('DELETE', 'session');		$result = $client->request('DELETE', 'session');
	</source>		</source>

Kfoster at 08:29, 19 October 2022

2022-10-19T08:29:17Z

← Older revision		Revision as of 10:29, 19 October 2022
Line 5:		Line 5:
	=Introduction=		=Introduction=

	LimeSurvey REST API v1 is available in LS 5.5.0 ~~or more recent which~~ offers '''various [https://api.limesurvey.org/swagger API endpoints]'''.		LimeSurvey REST API (v1) is available from LS 5.5.0 and offers '''various [https://api.limesurvey.org/swagger API endpoints]'''. The initial v1 REST API provides a subset of the functionality provided by the existing [https://manual.limesurvey.org/RemoteControl_2_API Remote Control API] except via a REST interface rather than an RPC interface.

	=Setup=		=Setup=
Line 11:		Line 11:
	==Configure==		==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'.		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==		==Security==

Kfoster at 16:04, 18 October 2022

2022-10-18T16:04:14Z

← Older revision		Revision as of 18:04, 18 October 2022
Line 1:		Line 1:
	TODO		; TODO - Under development
			: Available from version x (LS 5.5.0?)
	Under development		: Technical specification. UML.

	Available from version x (LS 5.5.0?)

	~~Available API endpoints~~

	Technical specification. UML.

	=Introduction=		=Introduction=

Kfoster: /* PHP Example */

2022-10-18T13:06:18Z

PHP Example

← Older revision		Revision as of 15:06, 18 October 2022
Line 68:		Line 68:
	==PHP Example==		==PHP Example==

			This example uses Guzzle as a PHP REST client but you can use any REST client.

	<source lang=bash>		<source lang=bash>