The Qlik Sense Repository Service (QRS) API is a REST API that you use to manage your Sense site programmatically. All the functionality you find in the Qlik Management Console is available via the QRS API.
The objects you manipulate in the QMC are represented in the QRS API as JSON entities. These entities have properties that coincide with the settings you find in QMC. The QRS API has a set of endpoints that work identically for all entity types. These general purpose endpoints allow you to create, retrieve, update, delete, and count entities in QRS. You can perform operations on subsets of entities using filters.
To help familiarize you with the QRS API, we will walk through some simple examples. You will learn how to:
- connect and send a simple request using Postman
- retrieve a listing of all endpoints
- retrieve a listing of all entities
- update an entity
Before you start, you will need to:
- install Postman
- know the URL for the computer where the Qlik Sense Repository Service (QRS) is installed
- know the URL for the computer where the Qlik Sense Proxy Service (QPS) is installed
Connecting to QRS
Depending on how you are authenticating your requests, you connect to QRS either directly or via the Qlik Sense Proxy Service. If you authenticate using a certificate, you must connect directly to QRS. If you use either Windows authentication or HTTP header authentication, you must connect via QPS.
To connect directly to QRS, you use the URL of the node where the Qlik Sense Repository Service is installed. By default, QRS listens for REST requests on port 4242, so the URL is:
https://qrs.computer.name.com:4242/<path>
To connect via the Qlik Sense Proxy Service, specify the URL for the node where QPS is installed (in a single node environment, this is the same URL as above, but without the port number):
https://qps.computer.name.com/<path>
To perform any operation in the QRS API, you must have the required permissions for the entity in question.
All QRS API requests must include both the Xrfkey parameter and the x-Qlik-Xrfkey header. These elements work together to prevent cross-scripting attacks. They must both contain the same 16 arbitrary characters.
In the examples that follow, we will authenticate with the current Windows user name, so we send our requests via the QPS URL. When you send POST commands via the QPS URL, they can sometimes fail because the session cookies have expired. To refresh the session cookies, simply issue another GET request. Postman will automatically update the session cookies in the subsequent requests, and they should proceed normally.
Issuing POST commands via the proxy
To connect and send a request:
- Open Postman and fill in the fields as shown below, replacing qps.computer.name.com with the URL to the computer where the Qlik Sense Proxy Service is installed:
This request connects to QRS via the Qlik Sense Proxy Service using the sender's Windows user name and retrieves information about the QRS API version.
- Click Send. The return value should look something like this:
{ "buildVersion": "2.11.0.0", "buildDate": "9/20/2013 10:09:00 AM", "databaseProvider": "Devart.Data.PostgreSql", "nodeType": 1, "schemaPath": "About" }
Discovering entities and endpoints
The QRS API provides mechanisms that help you to discover the entities and endpoints you can use to perform administrative tasks programmatically:
| To get: | Use: |
|---|---|
| All entity types and their default values | GET /qrs/about/api/default?listentries=[true|false] |
| The available endpoints in the QRS API | GET /qrs/about/api/description?extended=[true|false]&method=[GET|SET|PUT|POST]&format=JSON |
| The enumerations | GET /qrs/about/api/enums |
| The references between entities | GET /qrs/about/api/relations |
| An entity, initialized with default values, of a specific type | GET /qrs/about/api/default/[type]?listentries=[true|false] |
Retrieving a list of endpoints
In this example, we request all endpoints that use the PUT method. We want the extended response (which includes parameter types) and we want the response to be coded as JSON.
- Change the path portion of the URL in Postman to the following (leave the method as GET):
/qrs/about/api/description?extended=true&method=PUT&format=JSON
- Click Send. The return value should look something like this:
[ "{\"method\":\"PUT\",\"path\":\"/qrs/app/{id}/migrate\",\"extended\":\"[resource=manual, bodytype=Void, returntype=Void]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/{id}/publish?stream={streamid}&name={name}\",\"extended\":\"[resource=manual, bodytype=Void, returntype=App, optional=name]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/{id}/replace?app={appid}\",\"extended\":\"[resource=manual, bodytype=Void, returntype=App]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/{id}?privileges={appendprivileges}\",\"extended\":\"[resource=generated, bodytype=App, returntype=App, optional=privileges]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/object/{id}/publish\",\"extended\":\"[resource=manual, bodytype=Void, returntype=AppObject]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/object/{id}/unpublish\",\"extended\":\"[resource=manual, bodytype=Void, returntype=AppObject]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/app/object/{id}?privileges={appendprivileges}\",\"extended\":\"[resource=generated, bodytype=AppObject, returntype=AppObject, optional=privileges]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/appcontentquota/{id}?privileges={appendprivileges}\",\"extended\":\"[resource=generated, bodytype=AppContentQuota, returntype=AppContentQuota, optional=privileges]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/cloudcredentials/{id}?privileges={appendprivileges}\",\"extended\":\"[resource=generated, bodytype=CloudCredentials, returntype=CloudCredentials, optional=privileges]\"}", "{\"method\":\"PUT\",\"path\":\"/qrs/compositeevent/{id}?privileges={appendprivileges}\",\"extended\":\"[resource=generated, bodytype=CompositeEvent, returntype=CompositeEvent, optional=privileges]\"}", ... ]
Retrieving a list of entities
In this example, we request a list of all entities and their default settings, with all the contained entities fully listed as well.
- As before, change the path portion of the URL in Postman to the following (leave the method as GET):
/qrs/about/api/default?listentries=true
- Click Send. The return value should look something like this:
{ "App": { "id": "00000000-0000-0000-0000-000000000000", "name": "", "appId": "", "publishTime": "1753-01-01T00:00:00Z", "published": false, "stream": { "id": "00000000-0000-0000-0000-000000000000", "name": "", "privileges": null }, "savedInProductVersion": "", "migrationHash": "", "availabilityStatus": 0, "privileges": null }, "App.Content": { "id": "00000000-0000-0000-0000-000000000000", "maxFileSize": 0, "remainingLibrarySpace": 0, "privileges": null }, "App.DataSegment": { "id": "00000000-0000-0000-0000-000000000000", "metaDataObject": "", "name": "", "engineObjectId": "", "contentHash": "", "privileges": null }, "App.Internal": { "id": "00000000-0000-0000-0000-000000000000", "engineObjectType": "", "name": "", "engineObjectId": "", "contentHash": "", "privileges": null }, "App.Object": { "id": "00000000-0000-0000-0000-000000000000", "engineObjectType": "", "description": "", "objectType": "", "publishTime": "1753-01-01T00:00:00Z", "published": false, "name": "", "engineObjectId": "", "contentHash": "", "privileges": null }, "AppAvailability": { "id": "00000000-0000-0000-0000-000000000000", "privileges": null }, "AppContentQuota": { "id": "00000000-0000-0000-0000-000000000000", "maxFileSize": -1, "maxLibrarySize": -1, "privileges": null }, ... }
Updating an entity
When you update an entity, QRS performs an internal check using the modifiedDate property of that entity to ensure that no collisions occur. Because of this, you must always include the modifiedDate property in the body of all update requests. In addition, because QRS may substitute default values for omitted properties, we recommend that you always include the entire entity when you perform an update.
Updating an entity and handling PUT request conflict responses
In this example, we will update the maximum library size of the app content quota entity. Because there is only one app content quota entity, we use the /qrs/[type]/full endpoint to retrieve all the properties. If you know the ID of the entity, you can use /qrs/[type]/{id}, which always returns full entities, to get all the properties.
To update the app content quota entity:
- Change the path portion of the URL in Postman to the following (leave the method as GET):
/qrs/appcontentquota/full
- Click Send. The return value should look something like this:
{ { "id": "1001a995-e85d-4ecd-aa17-b66f3ac20c43", "createdDate": "2016-02-12T16:31:01.351Z", "modifiedDate": "2016-02-12T16:31:01.351Z", "modifiedByUserName": "INTERNAL\\sa_repository", "customProperties": [], "maxFileSize": 26214400, "maxLibrarySize": 52428800, "privileges": null, "schemaPath": "AppContentQuota" } - Change the method to PUT, and change the path portion of the URL in Postman to the following:
/qrs/appcontentquota/{id}
where {id} is the id field from the returned entity of the last request.
- Copy the entire returned entity from the last request into the body for this new request.
- Change the value of the maxLibrarySize to 62914560 (that is, from 50 Mb to 60 Mb).
- Click Send. The return value should look something like this:
{ "id": "1001a995-e85d-4ecd-aa17-b66f3ac20c43", "createdDate": "2016-02-12T16:31:01.351Z", "modifiedDate": "2016-07-23T18:371:16.221Z", "modifiedByUserName": "INTERNAL\\sa_repository", "customProperties": [], "maxFileSize": 26214400, "maxLibrarySize": 62914560, "privileges": null, "schemaPath": "AppContentQuota" }You should see that the modifiedDate property has been updated to today's date.
What to do next
Now that you have seen some commands in the QRS API, take a look at the examples and try setting up some different authentication methods. You can also try some of the special purpose endpoints, for example to start a task or view user information.
Here are some additional resources that can help you: