qix

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.

Use header Authorization: Bearer <token> with API key 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}

Error Handling

When something happens unexpectedly, the WebSocket may be closed with an error code and message. The error code will be a 4-digit number and the message may or may not be empty. The code below should be used for monitoring this.

ws.on("close", (code, message) => {
  console.log(code);
  console.log(String(message));
});

4204
{"code":"QEP-104","traceId":"491a33e544de8dda40a9fc9b0cb53216"}

The following is a list of error codes and their causes:

• 4202 - the WebSocket request appears to be malformed
• 4203 - the request could not be fulfilled because of a permissions issue
• 4204 - the request failed because something could not be found, this may be because the app id in the URL is wrong or the app has been deleted
• 4205 - the request could not be fulfilled because the system is busy, consider sending the request again later
• 4230 - the request could not be fulfilled because there are too many open apps in your organization
• 4240 - the request could not be fulfilled because there are no available engines

API references

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