Workspace Declarative API Interface

This article explains how to use the declarative API interface to manage workspaces. For a high-level overview of the declarative API interface, please refer to the declarative API interface documentation.

Managing Workspaces

The declarative API interface allows you to manage all workspace entities at once or all of the entities associated with their respective endpoint at once (logical data model (LDM), analytics layer, data filters).

The declarative API interface for workspaces uses the following endpoints:

  • /api/v1/layout/workspaces
    Manages all the workspaces in an organization at once
  • /api/v1/layout/workspaceDataFilters
    Manages all the workspace data filters in an organization at once
  • /api/v1/layout/workspaces/{workspace-id}
    Manages the whole declarative model for the specified workspace
  • /api/v1/layout/workspaces/{workspace-id}/logicalModel
    Manages the LDM for the specified workspace
  • /api/v1/layout/workspaces/{workspace-id}/analyticsModel
    Manages the analytics layer for the specified workspace

Where:

  • {workspace-id}
    Specifies the ID of the workspace to access. For example, headquarters.

Write Operations

Extended Metadata

Author and Editors

Analytical entities, such as analytical dashboards, dashboard plugins, visualizations, and metrics, carry metadata concerning their creation and the most recent edits. Using the declarative interface, you can modify or rebuild this information to suit your specific use case.

Backup and Restore

By default, the declarative analytics interface includes the following fields for the mentioned entities:

  • createdBy: Records the entity’s creator.
  • createdAt: Marks the timestamp of entity creation.
  • modifiedBy: Records the user responsible for the most recent modifications.
  • modifiedAt: Marks the timestamp of the last edit.

When undertaking a data restore operation, the API takes into account the values in the payload’s content.

Cloning and Migration

When using the layout endpoints for analytical layouts, you can add the exclude=ACTIVITY_INFO parameter to the GET method URI. This parameter guarantees that the response does not contain any details related to entity creation or the last edit. Reintroducing the analytics layout to the declarative API results in the createdAt field reflecting the upload time, while the createdBy field is assigned to the user who triggered the API.

Example:

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  $HOST_URL/api/v1/layout/workspaces/headquarters?exclude=ACTIVITY_INFO > workspace-backup-without-authors.json

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d @workspace-backup-without-authors.json \
  $HOST_URL/api/v1/layout/workspaces/headquarters2

See the Object Authors and Editors section for more details.

Example Requests

The examples in this section are not meant to be used without modification. Please modify the examples to match the requirements of your site before using them.

Backup a Workspace

The following example retrieves the entire declarative layout for the specified workspace and stores the output in a JSON file named workspace-backup.json.

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

Restore a Workspace

The following example replaces the workspace declarative layout for the specified workspace with that of a previously retrieved declarative layout.

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

Clone a Workspace

The following examples copy the layout of the workspace headquarters to a JSON file named workspace-backup.json and overwrites the layout of an existing workspace named headquarters2 with the contents of that file.

To prevent a 404 error, the target workspace of the overwrite (headquarters2 in this example) must first exist before you can issue a PUT request using the workspace {workspace-id}. For more information, see Create a Workspace.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  $HOST_URL/api/v1/layout/workspaces/headquarters > workspace-backup.json
curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X PUT \
  -d @workspace-backup.json \
  $HOST_URL/api/v1/layout/workspaces/headquarters2

Backup a Logical Data Model

The following example retrieves the LDM declarative layout for the specified workspace and stores the output in a JSON file named model.json.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" $HOST_URL/api/v1/layout/workspaces/headquarters/logicalModel > model.json

Restore a Logical Data Model

The following example replaces the LDM declarative layout for the specified workspace with that of a previously retrieved declarative layout.

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

Empty the Workspace of Logical and Analytical Objects and Data Filters

The following example removes all the objects from the specified workspace.

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

Backup All Workspaces

The following example retrieves the workspace declarative layouts for all workspaces associated with the organization hostname and stores the output in a JSON file named all-workspaces-backup.json.

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

Restore All Workspaces

The following example replaces the workspace declarative layout for all workspaces associated with the organization hostname with that of a previously retrieved declarative layout.

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

Workspace Declarative Layout Document

The following example shows a truncated declarative layout for workspaces. The workspace headquarters is a parent workspace that propagates all its attributes to the child workspace sub1.

{
  "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": []
        }
      },
      "settings": [
        {
          "id": "timezone",
          "content": {
            "value": "Europe/Prague"
          }
        }
      ]
    },
    {
      "id": "sub1",
      "name": "Subsidiary I.",
      "model": {
        "ldm": {
          "datasets": [],
          "dateInstances": []
        },
        "analytics": {
          "analyticalDashboards": [],
          "filterContexts": [],
          "metrics": [],
          "visualizationObjects": []
        }
      },
      "parent": {
        "id": "headquarters",
        "type": "workspace"
      },
      "settings": [
        {
          "id": "timezone",
          "content": {
            "value": "Europe/Prague"
          }
        }
      ]
    }
  ],
  "workspaceDataFilters": []
}