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 or all of the entities associated with their respective endpoints at once (e.g., logical data model, 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 logical data model (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

Important

Because the declarative API interface manages all workspace entities associated with their related endpoint at once, the contents of any PUT request that uses the declarative API interface will completely replace the contents of the existing declarative layout for the associated endpoint. Be sure to back up your model before making changes.
If you send a PUT request that affects only the logical model, then any analytical objects with a relationship to logical objects that no longer exist will become invalid. The relationship between logical and analytical objects cannot be re-established by issuing a PUT request with the previous version of the logical data model. The relationships must be restored manually, or you must issue a PUT request with the entire workspace (/api/v1/layout/workspaces) declarative layout.

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. You can modify or rebuild this information using the declarative interface 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.

The API considers the values in the payload’s content when undertaking a data restore operation.

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 contains no 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.

Note

In the following examples, the URL for the endpoint is represented with the $HOST_URL variable and the workspace identifier (name) is headquarters.

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 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 overwrite 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}. See Create a Workspace for more information.

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 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 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": []
}

Entity API Interface