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.

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

• GoodData.CN
  https://{organization-hostname}/api/v1/layout/workspaces
• GoodData.CN Community Edition
  http://localhost:{port}/api/v1/layout/workspaces

Where:

• {organization-hostname}
  Specifies the hostname for your organization with GoodData.CN. For example gooddata.com.
• {port}
  Specifies the port to access your installation of GoodData.CN Community Edition. The default port is 3000.

Write Operations

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 \
  $HOSTNAME/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 \
  $HOSTNAME/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 \
  $HOSTNAME/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 \
  $HOSTNAME/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" $HOSTNAME/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 $HOSTNAME/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": [] }
  }' \
  $HOSTNAME/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 \
  $HOSTNAME/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 \
  $HOSTNAME/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": []
        }
      }
    },
    {
      "id": "sub1",
      "name": "Subsidiary I.",
      "model": {
        "ldm": {
          "datasets": [],
          "dateInstances": []
        },
        "analytics": {
          "analyticalDashboards": [],
          "filterContexts": [],
          "metrics": [],
          "visualizationObjects": []
        }
      },
      "parent": {
        "id": "headquarters",
        "type": "workspace"
      }
    }
  ],
  "workspaceDataFilters": []
}