Creating and listing workspaces in Management API

On this page

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

See GET /api/stacks/ and POST /api/stacks/ in the API reference.

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:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/stacks/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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}}'

Filtering workspaces by UUID

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

Create a GET request to the following endpoint, replacing {{WORKSPACE_UUID}} with the UUID of the workspace:
```
https://{{INSTANCE}}/api/stacks/?uuid={{WORKSPACE_UUID}}
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/storage/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/stacks/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
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.
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.