QIX

v12.844.0

The JSON-RPC API over websocket that enables you to interact with the Qlik Associative Engine.

The QIX API is the primary API used for working with Qlik apps. It's based on the WebSocket protocol and requires some specific parameters to work correctly as seen below.

WebSockets

When you want to use the API, any websocket client implementation that follows the RFC specification should be supported. The URL format is:

wss://your-tenant.us.qlikcloud.com/app/<app id>

Browser example:

const websocket = new WebSocket('wss://your-tenant.us.qlikcloud.com/app/123e4567-e89b-12d3-a456-426655440000');

Headers

In a non-browser environment, most websocket client implementations support to add headers.

HeaderDescription
Authorization: Bearer <token>The API key to use for authentication.

Session sharing

When using the QIX API you build up a state in what's called a session. A session is based on a tenant, a user, and the app. When opening a new websocket you'd either get a new unique session, or get attached to an existing session. When sharing a session, the state (like selections), is shared between all websocket connections.

The conditions for sharing a session is:

  • The websocket URL needs to be identical (tenant URL and app id)
  • The user needs to be the same:
    • in a browser environment the same user needs to be signed in
    • in a non-browser environment an API key from the same user and tenant needs to be used

JSON-RPC protocol

The QIX API leverages the JSON-RPC protocol. It implements a superset of this specification. All requests sent from the client should contain the following properties:

{
  // Protocol descriptor:
  "jsonrpc": "2.0",
  // Session-unique numeric id, referred to in the response
  // to connect the request and response:
  "id": 6,
  // The handle for the object to interact with:
  "handle": 2,
  // The object type of the handle above decides
  // which API methods you may invoke:
  "method": "ApiMethodName",
  // Parameters for the invoked API method:
  "params": {
  }
}

Request and response

Here is an example request/response pair. Note that there is only one static handle in the QIX API, and that's -1. This handle refers to the Global API.

In this example request, an app is opened using OpenDoc. If successful, the response contains a reference to the app handle, which can be used to do further requests towards the Doc (app) API, and so forth.

{
  "jsonrpc": "2.0",
  "id": 1,
  "handle": -1,
  "method": "OpenDoc",
  "params": {
    "qDocName": "<app id>"
  }
}

If that app exist, the response would look similar to this:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "qReturn": {
        "qType": "Doc",
        "qHandle": 1,
        "qGenericId": "<app id>"
      }
    },
    "change":[1]
}

Note that qHandle contains the handle that might be used to make additional requests to invoke API methods towards the app. A property called change is also received on the response, an array that can be sent by QIX Engine on any responses and contains all open handles in your session that may have been invalidated and you should refetch data to ensure your application in a valid state.

Session apps

Session apps are non-persisted Qlik Sense apps created on-the-fly in server memory by the Qlik Associative Engine. You have to define a load script and trigger a data reload before any data model is accessible for each user session. Similarly, if you create a session app from an existing app, you have to trigger a reload after retrieving objects from the template app.

Session apps are attached to the active Qlik Associative Engine session. When a session ends, for example, by the user logging out, the session app is terminated and all related resources are released from server memory. Standard Qlik security rules ensure that only authenticated users can access data and visualizations from a session app.

WebSocket URL for session apps

The WebSocket URL for creating a session app has the following format: wss://my-tenant.us.qlikcloud.com/app/SessionApp_{appId}

You must append a unique app ID to SessionApp_ in the path. The app ID can be a code-generated random number.

To create a session app from an app, you must add the template app ID as a query parameter to the URL: wss://my-tenant.us.qlikcloud.com/app/SessionApp_{appId}?from={templateAppId}

API references

For the API references, see the different classes listed in the left-side menu.