General Information¶

This page lists information to access the API that is relevant for all endpoints.

Authentication¶

Authentication in QVANTUM relies upon the OpenID Connect protocol, being a simple identity layer on top of the OAuth 2.0 protocol. For third-party client authentication with the QVANTUM Public API, we particularly employ the OAuth 2.0 Password Grant. A valid access token is prerequisite to any use of the QVANTUM Public API. Such a token can be acquired in exchange for a set of credentials valid within the tenant context. The respective authentication request includes details such as tenant id, client id, credentials, and a fixed grant type.

Authentication Request with curl

curl --request POST \
  --header "Content-Type:application/x-www-form-urlencoded" \
  --data "grant_type=password" \
  --data "client_id=${CLIENTID}" \
  --data "username=${USERNAME}" \
  --data "password=${PASSWORD}" \
  "${AUTH}/auth/realms/${TENANT}/protocol/openid-connect/token"

In case of a successful authentication, the response body will include a JSON payload like the following. Most importantly, the payload includes an access token, which will be required in all subsequent calls to the QVANTUM Public API. For the rest of this tutorial, the environment variable TOKEN represents the value for a valid access token gathered by this initial request. By default, all access tokens will expire after 5 minutes. For refreshing an access token, the response also includes a refresh token, expiring after 30 minutes.

Authentication Response JSON Payload

{
  "access_token": "<TOKEN>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "7f97c7ba-aac8-4a26-854b-ecd833b67ac3",
  "scope": "profile email add_audience_plankit-service"
}

For all subsequent requests to the QVANTUM Public API, access token information is passed as Authorization header with value Bearer ${TOKEN}.

The QVANTUM Public API is designed as a REST-style API following the HATEOAS principle. As such, endpoints represent resources relevant in a planning domain. Besides resource-specific information, each resource also includes a set of links to itself and other resources, thus allowing navigation by following links in series of requests. Every navigation starts with the tenant collection as an entry point. Next, link relations are followed to the relevant resources (e. g. plans or cubes). Navigation to further resources not explicitly documented here follows the same principle.

Warning

Clients using the QVANTUM API must use navigations via link since URLs can change at any time. Only the entry point URL ${API}/api/v1/tenants is guaranteed to stay the same. The name of the links in the resources will not be changed or removed, therefore allowing for backward compatibility with older clients. If a client does not use navigation via links it may break at any time!

Navigating to a Tenant¶

With the availability of an access token, navigation starts with a request to the tenants resource, representing the list of all available tenant resources. The access token is passed via an authentication header Authorization with value Bearer ${TOKEN}, acquired during authentication.

Retrieve Tenant Information

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants'

The response payload includes a JSON representation of a one-element list of tenant representations. Besides an id, display name, and description, a tenant resource includes the following links:

allPlans: a link to a collection of all plan resources
plans: an array of links to the plan resources.
allUsers: retrieval link for user definition (cf. retrieve user definition)
userUploads: upload link for user definition (cf. upload user definition)
planning-app: link to planning web application

Tenant JSON Representation

{
  "tenants":[
    {
      "id":1,
      "displayName":"My Tenant",
      "description":"A tenant for me.",
      "_links":{
        "self": {
          "href":"https://api.qvantum-plan.de/api/1/tenants/1"
        },
        "allPlans":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans"
        },
        "plans":[
          {
            "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
          }
        ],
        "allUsers":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/users{?includeControllers}",
          "templated": true
        },
        "userUploads":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/userUploads"
        },
        "planning-app":{
          "href":"https://app.qvantum-plan.de/thinking-networks/"
        }
      }
    }
  ]
}

Navigating to a Plan¶

Within a tenant, QVANTUM supports a collection of plans. The allPlans link will return this collection. Currently, this is limited to one plan. Alternatively, starting from a tenant resource, following a link in the plans array provides a shortcut to the URL of the plan resource. A request to this resource provides information about the respective planning application, including further navigation links.

Retrieve Plan Information

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  '${PLAN_LINK}'

The response payload includes a JSON representation of the plan resource. Besides an id, title, status and end date, a plan resource includes the following links:

owner: owning tenant
uploads: endpoint for planning model metadata (cf. upload planning model).
allCubes: list of all cube resources within this plan
allStructures: list of all structure resources within this plan
allPermissions: upload resp. retrieval link for permission assignment (cf. upload permission assignment resp. retrieve permission assignment)
structuresUploads: endpoint can be used to update structures

The "status" field may have only these values:

NOT_STARTED : the workflow has not been started yet.
RUNNING : the workflow is running.
PAUSED : the workflow has been paused.
FINISHED: the workflow has been finished.
EXPORTED: the workflow has been finished and the data has been exported.

Updates of title, endDate and status can be updated with a PATCH request (cf. Update a Plan).

Plan JSON Representation¶

{
  "id": 1,
  "title": "My Plan",
  "endDate": "2022-09-30T21:59:59Z",
  "status": "<WORKFLOW_STATUS>",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
    },
    "owner":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1"
    },
    "uploads":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/uploads"
    },
     "allStructures": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures=planId=1"
    },
    "allCubes":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes?planId=1"
    },
    "allPermissions": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/permissions"
    },
    "structuresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/structuresUploads"
    }
  }
}

Navigating to a Cube¶

Within a plan, QVANTUM supports a set of cubes. As for plans within tenants, this set is currently limited to one cube per plan. Starting from a plan resource, following the link allCubes leads to a cube collection resource, listing all available cubes.

Retrieve Cube List

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${ALL_CUBES_LINK}'

Retrieve Single Cube

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${CUBE_LINK}'

The response payload includes a JSON representation of a one-element array of cube representations. Besides an id, business key, display name, and description, each cube representation includes the following links:

dimensions: array of links to this cube's dimension resources.
keyFigures: export link for the key figures (cf. export key figures)
keyFiguresUploads: upload link for the key figures (cf. upload key figures)
dataUploads: upload link for cube cell data (cf. upload initial data)
data: download link for cube cell data (cf. export cell data / delete cell data)
template: download link to cube cell data template (cf. download data template)
modelUploads: upload link for full model updates (cf. upload full model update)
allExternalForms: import/export link for forms (cf. export and import forms)

Single Cube JSON Representation

{
  "id": 1,
  "businessKey": "MYCUBE",
  "displayName": "My Cube",
  "description": "A cube for me.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1"
    },
    "plan":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
    },
    "dimensions":[
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/2"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/3"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/4"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/5"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/6"}
    ],
    "keyFigures": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/keyFigures"
    },
    "keyFiguresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/keyFigures/uploads"
    },
    "dataUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dataUploads"
    },
    "data":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/cells{?dimensionRestrictions,inputAllowedFilter}"
    },
    "template":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/template"
    },
    "modelUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/modelUploads"
    },
    "allExternalForms": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/forms"
    }
  }
}

Navigating to a Dimension¶

A cube is substantial part of the model behind a plan. A cube mainly consists of a set of dimensions. Detailed information on the structure of a planning model is available in section Planning model definition.

Starting from a cube, following one of the dimension links leads to a dimension resource.

Retrieve Single Dimension

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${DIMENSION_LINK}"

The response payload includes a JSON representation of a single dimension. Besides an id, business key, and description, each dimension representation includes singular and plural labels (singularName, pluralName) and a link structure enabling the navigation to the structure, defining the elements of a dimension (cf. next section).

Single Dimension JSON Representation

{
  "id": 1,
  "businessKey": "KF",
  "singularName": "Key Figure",
  "pluralName": "Key Figures",
  "description": "A dimension for key figures.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1"
    },
    "cube":{
      "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/cubes/1"
    },
    "structure":{
        "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/structures/1"
    }
  }
}

Navigating to all Structures¶

Within a plan, QVANTUM supports a set of structures. Starting from a plan resource, following the link 'allStructures' leads to a structure collection resource, listing all available structures with their elements as described here.

Structure List

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  --header "Accept:application/x.de.qvantum-plan.external-structures+json" \
  '${ALL_STRUCTURES_LINK}'

Navigating to a Structure¶

Conceptually, each dimension is defined by an underlying structure and its elements.

Starting from a dimension, following the structure link leads to a structure resource.

Retrieve Single Structure

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${STRUCTURE_LINK}"

The response payload includes a JSON representation of a structure. Besides an id, business key, display name, description and further properties, each structure representation includes a link upload, allowing the upload of updates, in particular updates on the structure and the dimension based on it (cf. updating planning models).

Structure JSON Representation (extract)

{
  "id": 1,
  "businessKey": "COSTCENTERS",
  "displayName": "Cost Centers",
  "description": "A structure defining a set of cost centers",
  ...
  "customAttributes": [
    {
      "businessKey": "COSTCENTERCLASS",
      "displayName": "Cost Center Class",
      "description": "Attribute to document different classes of cost centers",
      "attributeType": "TEXT"
    }
  ],
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures/1"
    },
    "plan":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plan/1"
    },
    "upload": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures/1/upload"
    }
    ...
  }
}

Localization¶

Some endpoints deliver localizable texts, e.g. log entries when uploading planning models. The desired locale can be specified using the Accept-Language header. Supported locales are en, de (default) and de-CH.

Specifying Locale in Request

curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  --header "Accept-Language:en"
  "${MODEL_UPLOAD_LINK}"