Workspace Declarative API Interface

Declarative API

Check high-level overview of the Declarative API Interface first.

Manage workspace metadata

There are endpoints to manipulate the model:

  • /api/layout/workspaces to set all workspaces in organization at once (logical + physical + analytics layer)
  • /api/layout/workspaceDataFilters to set all workspace data filters in organization at once
  • /api/layout/workspaces/<workspace-id> to set whole model at once (logical + physical + analytics layer)
  • /api/layout/workspaces/<workspace-id>/logicalModel to set logical + physical layer of the model
  • /api/layout/workspaces/<workspace-id>/analyticsModel to set analytics layer of the model

Whenever you put a new model, the previous version is fully replaced. When putting logical model only, then relations from analytical objects to no longer existing logical objects will be deleted too, so the influenced analytics objects might become invalid, ex. metrics are not computable, insights cannot be visualized. These relations cannot be fixed by putting back the previous version of the model, they must be restored manually or whole model must be restored.

Document for the complete model endpoint can be used on logical or analytics endpoint eventually and then relevant part will be processed only.

To see the entire API specification, visit API reference .

Write operations warning

The user must be careful when write new declarative model through API. Immediately before write new values ALL previous values are deleted. It is user business to back up all data before write operation.

Examples

First, be aware of your application endpoint. For Helm Chart deployment, it represents the https://<organization-hostname> value. For All-in-One docker image, the default endpoint is http://localhost:3000.

In the following examples:

  • the endpoint is substituted by $ENDPOINT variable;
  • the workspace identifier (name) used here is my-space.

Backup single workspace

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  $ENDPOINT/api/layout/workspaces/my-space > workspace-backup.json

Restore single workspace

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d @workspace-backup.json \
  $ENDPOINT/api/layout/workspaces/my-space

Clone workspace

Combination of two previous examples.

GET logical model

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" $ENDPOINT/api/layout/workspaces/my-space/logicalModel > model.json

PUT logical model

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d @model.json $ENDPOINT/api/layout/workspaces/my-space/logicalModel

Clean model using an empty boilerplate

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
  "ldm": { "datasets": [], "dateInstances": [] },
  "analytics": { "analyticalDashboards": [], "filterContexts": [], "metrics": [], "visualizationObjects": [] }
  }' \
  $ENDPOINT/api/layout/workspaces/my-space

Backup all workspaces

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  $ENDPOINT/api/layout/workspaces > all-workspaces-backup.json

Restore all workspaces

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d @all-workspaces-backup.json \
  $ENDPOINT/api/layout/workspaces

Workspace layout document

{
  "workspaces": [
    {
      "id": "headquarters",
      "name": "Headquarters",
      "model": {
        "ldm": {
          "datasets": [],
          "dateInstances": [{
            "description": "parent date",
            "granularities": [
              "DAY",
              "WEEK",
              "MONTH",
              "QUARTER",
              "YEAR"
            ],
            "granularitiesFormatting": {
              "titleBase": "",
              "titlePattern": "%granularityTitle (%titleBase)"
            },
            "id": "date.parent",
            "title": "Hierarchy Date"
          }]
        },
        "analytics": {
          "analyticalDashboards": [],
          "filterContexts": [],
          "metrics": [],
          "visualizationObjects": []
        }
      }
    },
    {
      "id": "sub1",
      "name": "Subsidiary I.",
      "model": {
        "ldm": {
          "datasets": [],
          "dateInstances": []
        },
        "analytics": {
          "analyticalDashboards": [],
          "filterContexts": [],
          "metrics": [],
          "visualizationObjects": []
        }
      },
      "parent": {
        "id": "headquarters",
        "type": "workspace"
      }
    }
  ],
  "workspaceDataFilters": []
}