informatiqal / qlik-saas-api

Interact with Qlik Sense SaaS REST APIs

Qlik Sense SaaS REST API

Node.js module to interact with Qlik Sense SaaS API

UNDER DEVELOPMENT

NOT AFFILIATED WITH QLIK

Installation

npm install qlik-saas-api

Note Node version >= 16.0.0

Note Please open and issue if you are experiencing problems with the tabular reporting related methods - sharing tasks, report templates and report filters. The API itself is quite complicated and its hard to test and verify

Authentication

At this moment only JWT authentication is supported

Usage

Initialize the client

import { QlikSaaSApi } from "qlik-saas-api";

const saasApi = new QlikSaaSApi.client({
  host: "tenant-url",
  authentication: {
    token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  },
});

List of available methods:

List of apps methods:

Details for an app:

Methods

Full list of available methods can be found here

Breaking changes

After v0.10.0

Prior v0.10.0 some methods were expecting named parameters and some were expecting the arguments to be an object. From v0.10.0 onwards all public methods will expect their arguments to be an object.

Old:

async get(id: string) { ... }

New:

async get(arg: { id: string }) { ... }

The new way of calling these methods will be:

await something.get({ id: "some-id here" })

Instead of:

await something.get("some-id here")

In the future v2.0

Breaking changes will be introduced in the future v2+ of the package

• All methods that require arguments will expect the arguments to be passed as an object

  Current:

  let updateResponse = await app.addToSpace("space-id-here");

  New:

  let updateResponse = await app.addToSpace({ spaceId: "space-id-here" });

  There are two reasons for that:

  • consistency - the other Qlik REST API packages (Repository, Proxy etc.) are using the same approach
  • easier to use this package as part of Automatical and Automatical-CLI

• At the moment some methods are returning the details instead of the instance. Code review will be performed and for these methods the return will be changed to class instance

Note In order to avoid usage issues the package will be released in two versions - v1+ and v2+. All new features, fixes, patches etc will be applied to both versions. v2+ will be the default version and v1+ will be installed with:

npm install qlik-saas-api@v1

Rate limit

From 01/11/2022 Qlik is introducing rate limits when using SaaS REST API. If the response is with status 429 then the rate limit is reached and the script have to wait before continue.

(from community.qlik)

Tier	Limit	Description
Tier 1	600+ per minute	Supports majority of requests for data consumption with generous bursting.
Tier 2	60+ per minute	Create, update, and delete resource endpoints with occasional bursts of more requests.
Special	Varies	Rate limiting conditions are unique for methods with this tier. Consult the method's documentation to better understand its rate limiting conditions.

For more information please check these links:

• qlik.dev
• qlik community post 1
• qlik community post 2

qlik-saas-api's Issues

Rate limit info

Add rate limit information (at least in the readme). Start from here

Zod implementation

Just to not forget that at some points have to start using Zod as arguments validator tool

App reload logs

Implement /apps/reloads/logs endpoints

saasClient and id - do not expose?

At the moment saasClient and id class properties are public. These have to be made private (other way to not expose them?).

When public then the whole config is exposed - this will include any authentication information, that is used to communicate with Qlik API's

id ... not a big deal that is exposed but might be good to "hide" it as well.

Class interface implementation

At the moment all classes are implementing interface. Think this is not necessary and its not benefiting anything

Init to check for empty object

Its not major issue but the init method should check if details variable have any properties as well. At the moment the only check is if details is not defined

Inline variables with nested properties

When using inline variables and provide property name to extract it will not work when the value is nested in the object eg. $${Some task name#someProperty.anotherLevel.myValue}.

The function that is parsing the inline variables should respect that and should work with nested values

Remove filter

removeFilter should be implemented similarly to #199 (and rename the existing removeFilter to removeFilterNative)

Brands API Implementation

Blog post - https://qlik.dev/changelog/2023-05-09-3

Automation APIs

General issue to track the implementation of the Automation API https://qlik.dev/apis/rest/automations

Users API - Invite implementation

Blog post - https://qlik.dev/changelog/2023-05-09

apps.create - name ignored

When creating new app and passing name argument the created app's name is guid instead of the name provided.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency dotenv to v16.4.5
• Update dependency typedoc to v0.25.13
• Update dependency @types/node to v20.12.12
• Update dependency rollup to v4.17.2
• Update dependency typescript to v5.4.5
• Update dependency vitest to v1
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

npm

package.json

• form-data ^4.0.0
• qlik-rest-api ^1.8.3
• @rollup/plugin-typescript ^11.1.6
• @types/form-data ^2.5.0
• @types/node 20.11.19
• dotenv 16.4.4
• esm ^3.2.25
• nyc 15.1.0
• rollup ^4.12.0
• rollup-plugin-delete 2.0.0
• ts-node 10.9.2
• tslib ^2.6.2
• typedoc 0.25.8
• typescript 5.0.4
• vitest ^0.34.6
• node >=14.19.1

---

• Check this box to trigger a request for Renovate to run again on this repository

Generics as return type from qlik-rest-api

Because of Informatiqal/qlik-rest-api#81 code review is required. There is a good chance that a lot will be changed but the changes (related to the generics) will not affect the functionality itself

Item vs App

The problem arises from the fact that in order to get a list of the apps the endpoint is /items?resourceType=app,qvapp,qlikview and the rest of the app related apis are through /apps endpoints. And /items returned data is different from /apps/import (for example) returned data. And we are in position where dealing with the same entity type but with two data formats.

In order to "unify" the data format all app methods should get their final data from the /items endpoints

sort parameter for getAll

Add the optional sort parameter for all getAll methods. Similar to what is available for automationConnections.getAll() method.

And just in general ... what should be the approach for adding this? Extend the URLBuild class? or something simpler?

New API: Groups

Main issue #53

Implement new Groups API endpoints https://qlik.dev/apis/rest/groups

New API: Roles

Main issue #53

Implement new Roles API endpoints https://qlik.dev/apis/rest/roles

This is very dangerous!

qlik-saas-api/src/modules/Space.ts

Line 89 in 8d64242

.Delete(`spaces/${this.id}/assignments`)

there should be probably GET instead DELET?

API Updates - Users, Groups and Roles

Qlik is updating their API with the following changes:

• New API: Roles
• New API: Groups
• API Deprecations: Users

Source: https://qlik.dev/changelog/api-updates---users-groups-and-roles

Passing arguments change

All public methods, that expect some arguments, should have their arguments passed as an object and not as named parameters. For example:

Current:

async update(name: string) {
...
}

To be:

async update(arg: { name: string }) {
...
}

The main reason for this is because of Automatiqal (CLI) package(s). Qlik Repo API package already uses the same approach as well

All create methods to return instance

Double check that all create methods are returning an instance of an entity instead of the old approach that was returning the response data.

Just noticed that webIntegrations.create is not returning instance of an object

Import extension

Seems that import extension method is not implemented

Additional "actions"?

Can see possibility of adding "actions" (is this a good name?) for some entities.

For example:
At the moment the methods for App entity reflect the API endpoints. But what about add additional methods under "actions" property. These additional methods are not part of the /apps endpoints but are related to the apps. For example - reload-task. When creating reload-task the API requires appId. Which means that there is a direct link between reload task and app. The action in this case will be (something like):

// create reload task directly from the app instance
const app = await saasApi.apps.get("1234-1234-1234-1234");
const reloadTask = await app.actions.createReloadTask({ "reload-task-details-here" });

// get reload tasks for the specified app from the app instance
const app = await saasApi.apps.get("1234-1234-1234-1234");
const reloadTasks = await app.actions.getReloadTasks();
// reloadTasks will contain only the reload tasks "linked" with the current app

Probably most of these actions (if not all) can be applied only to app instances.

The questions are:

• any reason why not to?
• what are the code implications of such implementation
• (very wild question) if direct implementation will make the code unstable then what about implementing mixin/extension capability?!?!?!

WebHooks - update with the latest data changes

Seems that WebHooks types were updated at some point.

Make sure that the latest types are used + update the create and update methods with the latest changes

Deprecation of the evaluations API

Qlik announced API changes. https://qlik.dev/changelog/deprecation-of-the-evaluations-api

This issue is to track the overall changes implementation

New API: Tenant deletion API endpoints

• Blog post
• Documentation

Page size

For all getAll methods will be good to implement larger page size. By default Qlik will return the first 10 rows of data. But if the data is 100 rows (for example) then the rest client will have to make additional 10 requests (10 x 10 = 100) in order to get the full dataset. 50 items per page is probably ok?

The way to achieve this is to add limit=50 query parameter to the url for all getAll methods

Export/Download methods to return extra data

At the moment export/download methods are returning the raw data. This should be changed so the raw data to be returned under the file property and other extra information to be returned under additional properties.

For example app.export to return:

{
  "file": "Binary-data-here",
  "name": "qlik-app-name.qvf",
  "id": "123-123-123-123"
}

Additional _actions

#77 added few _actions to the App instance. This issue is to track what other entities can benefit from having an _action methods as well

App script versions

Implement /app/scripts endpioints

Number of calls made and rate limit info

Is it worth it for the instance to have count of calls made (by Tier) and approximate the rate limit "speed" (per minute)

Apps API changes implementation

Blog post - https://qlik.dev/changelog/2023-05-09-2

Oauth M2M authentication implementation

Qlik released OAuth authentication workflow. In general the authentication workflow will provide access_token that can be passed to the request to authenticate.

Have to allow the config to accept client_id and client_secret. If/when these two properties are passed then the logic should send request to oauth/token to receive the token details (the token itself and the expiration date).

The instance will hold the token and its expiration data and will try to re-use the token if not expired. If the token is expired then the instance will obtain a new one.

Blog post
Rest API examples

Sharing tasks

https://qlik.dev/apis/rest/sharing-tasks/

New API - reload tasks

Implement the new reload-tasks endpoints

https://qlik.dev/changelog/new-api---reload-tasks

App id vs resourceId

Since apps information is extracted via the /items endpoint the data returned includes the item id under the id property and the app id under the resourceId property.

This works fine but the problem is that all specific app operations are using the resourceId value. Because of this there should be an optional option, when creating app instance, to swap id and resourceId values.

This is not mandatory but makes filtering easier - no need to remember that when dealing with app resourceId should be used instead of id

Automated API changes

Check the automated API definition tracker for anymore changes
https://github.com/countnazgul/qlik-api-definitions

app.update - returns array instead of the app data

Since the app(s) data is returned from the /items api the response is an array. for app.update the array is returned instead of the first (and only) value

API Changes

According to countnazgul/qlik-api-definitions@31c2d7a there are new api changes.

Review and update!

Filtering

The current implementation follows the available SaaS api specs.

Unfortunately not all methods provide filtering capability by themselves. In contrast Repo API have dedicated filtering endpoints which are quite useful.

This issue is to somehow bring the same filtering capabilities to the SaaS API package. Its not going to be real filtering at the end of the day - in the background the package will get all entities and will filter the data based on the provided filter

API Updates - Groups, Tenants & Users

More API changes - Blog post

New API: Tansport

Implement the new API endpoints

• Blog post
• Documentation

Data alerts endpoints

Implement methods for Data Alerts

More authentication methods

At the moment only api keys are supported. More methods should be supported

New API: Lineage graphs

Implement Lineage graphs API endpoints

• Changelog/Blog post
• API Documentation

Always return instance or entiry

Majority of get/getAll/create etc methods should return instance of the entity, instead of the data/details for the entity. The rule is that if there are operations, that can be performed on the entity (like delete and update), the instance should be returned. And if there are no operations then data/response data is returned

New API: AutoML Real time Predictions

Implement the new API endpoints

• Blog post
• Documentation

Missing ednpoint - reloads -cancel

Missing the endpoint that can cancel running app reload - POST/v1/reloads/{reloadId}/actions/cancel (doc link)

API Deprecation: Users

Main issue #53

Investigate what are the implications of deprecation of user endpoints https://qlik.dev/changelog/api-updates---users-groups-and-roles#api-deprecations-users