|
|
| (3 intermediate revisions by 2 users not shown) |
| 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.
| |
| | |
| =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.
| |
| | |
| =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 https://api.limesurvey.org/swagger].
| |
| | |
| ==API Location==
| |
| | |
| The REST API URL is [http://www.yourdomain.com/rest/v1 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 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 to endpoints that require authorisation.
| |
| | |
| ===Logout===
| |
| To logout of the REST API perform an authorised DELETE request to the ''/rest/v1/session''.
| |
| | |
| ==Endpoints==
| |
| | |
| See the [https://api.limesurvey.org/swagger Swagger Documentation] for full details.
| |
| | |
| ; /rest/v1/
| |
| : session
| |
| : siteSettings
| |
| : siteSettings/<setting-name>
| |
| : survey
| |
| : survey/<id>
| |
| : questionGroup/<surveyId>
| |
| : questionGroup
| |
| : questionGroup/<groupId>
| |
| : questionGroupProperties/<groupId>
| |
| : questioGroupProperties/<groupId>
| |
| | |
| =Examples=
| |
| | |
| ==PHP Example==
| |
| | |
| This example uses Guzzle as a PHP REST client but you can use any REST client.
| |
| | |
| <source lang=bash>
| |
| composer require guzzlehttp/guzzle:^7.0
| |
| </source>
| |
| | |
| or by inclusion of the following lines in your composer.json file:
| |
| | |
| <source lang=javascript>
| |
| {
| |
| "require": {
| |
| "guzzlehttp/guzzle": "^7.0"
| |
| }
| |
| }
| |
| </source>
| |
| | |
| This is an example how to connect to limesurvey REST API:
| |
| | |
| <source lang="php">
| |
| <?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 = json_decode((string) $loginResult->getBody(), true);
| |
| } else {
| |
| throw new Exception('Login failed: ' . $result->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 ($result->getStatusCode() == 200) {
| |
| $siteName = json_decode((string) $result->getBody(), true);
| |
| } else {
| |
| throw new Exception('Failed getting site name: ' . $result->getStatusCode());
| |
| }
| |
| | |
| echo 'Site name: ' . $siteName;
| |
| | |
| // Logout
| |
| $result = $client->request('DELETE', 'session');
| |
| </source>
| |