Creating and listing workspaces in Management API

Creating and listing workspaces in Management API#

This guide explains how to create and list workspaces (called stacks in the Management API) with the Management API.

Note

Unless self-service key management is enabled for your workspace, a user with the Workspace Manager role cannot create a Connect API key. A root workspace Administrator must create a key with the workspace permission and give it to them. The key gives access only to its own workspace and the workspaces below it. For more information, see Authorizing to Management API.

Prerequisites#

  • Use a Connect API key with the following permissions:

    • Workspace: Read-only (workspace:read) to list workspaces and storage entries.

    • Workspace: Write (workspace:write) to create or update workspaces.

    Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

  • A Connect API key cannot delete a workspace. For more information, see Deleting a workspace.

Listing existing workspaces#

To list existing workspaces, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/stacks/

  2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

  3. Send the request.

As a result, you obtain the list of available workspaces in Management API and their IDs in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/stacks/' \
--header 'Authorization: Bearer {{KEY}}'

Note

The response includes a uuid field for each workspace. You can use this UUID to filter the list, as described below.

Filtering workspaces by UUID#

To retrieve a specific workspace by its UUID, follow these steps:

  1. Create a GET request to the following endpoint, replacing {{WORKSPACE_UUID}} with the UUID of the workspace:

    https://{{INSTANCE}}/api/stacks/?uuid={{WORKSPACE_UUID}}

  2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

  3. Send the request.

As a result, you obtain the workspace matching the specified UUID.

The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/stacks/?uuid={{WORKSPACE_UUID}}' \
--header 'Authorization: Bearer {{KEY}}'

Listing available storages#

To list available storages, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/storage/

  2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

  3. Send the request.

As a result, you obtain the list of available storage options.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/storage/' \
--header 'Authorization: Bearer {{KEY}}'

Creating a new workspace#

To create a new workspace (called Stack in Management API), follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/stacks/

  2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the following code as raw JSON input, and then replace the placeholder values as necessary.

    {
   "datalake_id": STORAGE_ID,
   "name":"NAME_OF_NEW_WORKSPACE",
   "parent_id": PARENT_ID
}

    Replace the following:

    • STORAGE_ID: Include the value of the parameter id in the API response where you list available storages. To obtain the described list, follow the procedure in Listing available storages.

    • NAME_OF_NEW_WORKSPACE: Choose any name for your new workspace which does not currently exist.

    • PARENT_ID: Optional. The ID of the workspace to set as the parent of the new workspace. The specified workspace becomes the parent of the new workspace, which inherits some of its configuration. If omitted, the workspace is created under the default parent workspace. To find the PARENT_ID, search for the value of the parameter id in the response to the request described in Listing existing workspaces.

  5. Send the request.

As a result, you created a new workspace through the Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/stacks/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datalake_id": STORAGE_ID, "name":"NAME_OF_NEW_WORKSPACE", "parent_id": PARENT_ID}'

Deleting a workspace#

A Connect API key cannot delete a workspace, whichever permissions it has. The workspace:write permission covers creating and updating workspaces only. To delete a workspace, use the Adverity user interface.

Warning

Deleting a workspace also deletes all its child workspaces and removes every authorization granted anywhere in that workspace tree.

Contents