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.
curl -X POST \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=${CLIENTID}" \
-d "username=${USERNAME}" \
-d "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.
{
"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}
.
Navigation¶
The QVANTUM Public API is designed as a REST-style API following the HATEOAS principle. As such, endpoints represent resources relevant in a planning application 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. The typical navigation starts with the tenant as entry point, then follows a link to a planning application under this tenant, and in turn follows a link to a cube under this planning application. Navigation to further resources not explicitly documented here follows the same principle.
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.
curl -i -X GET \
-H "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:
allPlanningApplications
: a link to a collection of all planning application resourcesplanningApplications
: an array of links to the planning application 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
Important
Previous versions of this document incorrectly suggested that planningApplications
is always a single link.
{
"tenants":[
{
"id":1,
"displayName":"My Tenant",
"description":"A tenant for me.",
"_links":{
"self": {
"href":"https://api.qvantum-plan.de/api/1/tenants/1"
},
"allPlanningApplications":{
"href":"https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications"
},
"planningApplications":[
{
"href":"https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/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 Planning Application¶
Within a tenant, QVANTUM supports a collection of planning applications.
The allPlanningApplications
link will return this collection.
Currently, this is limited to one planning application.
Alternatively, starting from a tenant resource, following a link in the planningApplications
array provides a shortcut to the
URL of the planning application resource.
A request to this resource provides information about the respective planning
application, including further navigation links.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
'${API}/api/v1/tenants/1/planningApplications/1'
The response payload includes a JSON representation of the planning application resource. Besides an id, display name and description, a planning application resource includes the following links:
owner
: owning tenantuploads
: endpoint for planning model metadata (cf. upload planning model).allCubes
: list of all cube resources within this planning applicationallPermissions
: upload resp. retrieval link for permission assignment (cf. upload permission assignment resp. retrieve permission assignment)allWorkflowInstances
: list of all workflow instance resources within this planning applicationstructuresUploads
: endpoint can be used to upload structures
Planning Application JSON Representation¶
{
"id": 1,
"displayName": "My Planning Application",
"description": "A planning application for me.",
"_links":{
"self":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
},
"owner":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1"
},
"uploads":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/uploads"
},
"allCubes":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes"
},
"allPermissions": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/permissions"
},
"allWorkflowInstances": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/workflowInstances"
}
"structuresUploads": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/structuresUploads"
}
}
}
Navigating to a Cube¶
Within a planning application, QVANTUM supports a set of cubes. As for planning applications within tenants,
this set is currently limited to one cube per planning application. Starting from a planning application resource,
following the link allCubes
leads to a cube collection resource, listing all available cubes.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
'${API}/api/v1/tenants/1/planningApplications/1/cubes'
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
'${API}/api/v1/tenants/1/planningApplications/1/cubes/1'
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)
{
"id": 1,
"businessKey": "MYCUBE",
"displayName": "My Cube",
"description": "A cube for me.",
"_links":{
"self":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1"
},
"planningApplication":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
},
"dimensions":[
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/1"},
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/2"},
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/3"},
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/4"},
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/5"},
{"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/6"}
],
"keyFigures": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/keyFigures"
},
"keyFiguresUploads": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/keyFigures/uploads"
},
"dataUploads": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dataUploads"
},
"data":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/cells{?dimensionRestrictions,inputAllowedFilter}"
},
"template":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/template"
},
"modelUploads": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/modelUploads"
},
"allExternalForms": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/forms"
}
}
}
Navigating to a Dimension¶
A cube is substantial part of the model behind a planning application. 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.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
"${API}/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/1"
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).
{
"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/planningApplications/1/cubes/1/dimensions/1"
},
"cube":{
"href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/planningApplications/1/cubes/1"
},
"structure":{
"href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/planningApplications/1/structures/1"
}
}
}
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.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
"${API}/api/v1/tenants/1/planningApplications/1/structures/1"
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 planning application updates,
in particular updates on the structure and the dimension based on it
(cf. updating planning applications).
{
"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/planningApplications/1/structures/1"
},
"planningApplication":{
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
},
"upload": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/structures/1/upload"
}
...
}
}
Navigating to a Workflow Instance¶
Within a planning application, QVANTUM supports a workflow process. As for planning applications within tenants,
this set is currently limited to one workflow instance per planning application. Starting from a planning application resource,
following the link allWorkflowInstances
leads to a collection resource, listing all available workflow instances.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
'${API}/api/v1/tenants/1/planningApplications/1/workflowInstances'
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
'${API}/api/v1/tenants/1/planningApplications/1/workflowInstances/1'
The response payload includes a JSON representation of a single worklflow instance. Besides an id, title and end date, the workflow instance representation includes a self link and a link to the underlying planning application. These fields may be updated by a separate request (cf. Update a Workflow)
{
"id": 1,
"title": "Financial Planning",
"endDate": "2022-09-30T21:59:59Z",
"status": "<WORKFLOW_STATUS>",
"_links": {
"self": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/workflowInstances/1"
},
"planningApplication": {
"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
}
}
}
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.
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
.
curl -i -X GET \
-H "Authorization:Bearer ${TOKEN}" \
-H "Accept-Language:en"
"${PLANNING_APP_URL}/uploads/1"