API Reference

Storage Pools

This page covers configuration and management of View storage pool objects.

Object Overview

Storage pools define where physical data written to object storage buckets resides.

Endpoint, URL, and Supported Methods

Objects are managed via the storage server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/pools.

By default, the storage server is accessible on port 8001 for the View REST API, and 8002 for the S3-compatible API. Note: storage pools are not manageable via the S3 API.

Supported methods include: GET HEAD PUT DELETE

Structure

Storage pool objects can have one of many structures depending on the type of storage pool. Currently, local disk, Amazon S3, and Azure BLOB storage pools can be configured. For assistance with configuring an Amazon S3 storage pool or an Azure BLOB storage pool, contact support.

A fully populated storage pool using local disk is shown below.:

{
    "GUID": "default",
    "TenantGUID": "default",
    "Name": "default",
    "Provider": "Disk",
    "WriteMode": "GUID",
    "UseSsl": false,
    "DiskDirectory": "./disk/",
    "Compress": "None",
    "EnableReadCaching": false,
    "CreatedUtc": "2024-07-10T05:09:32.000000Z"
}

Properties:

  • GUID GUID globally unique identifier for the object
  • TenantGUID GUID globally unique identifier for the tenant
  • Name string name of the object
  • Provider enum provider of the storage pool; this value should be Disk
  • UseSsl bool used by Amazon S3 and Azure BLOB storage pools
  • DiskDirectory string relative or full path to the disk repository where data should be stored
  • Compress enum the type of compression to apply; this value should be None
  • EnableReadCaching bool enable or disable read caching; this value should be false
  • CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/pools with the properties of the storage pool as defined above, using the storage server.

Note: once a storage pool has been written, it cannot be updated.

curl -X PUT http://localhost:8001/v1.0/tenants/[tenant-guid]/pools \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [accesskey]" \
     -d '
{
    "Name": "My disk storage pool",
    "Provider": "Disk",
    "WriteMode": "GUID",
    "UseSsl": false,
    "DiskDirectory": "./disk/",
    "Compress": "None",
    "EnableReadCaching": false
}'

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const createStoragePool = async () => {
  try {
    const response = await storage.createStoragePool({
      Name: "My disk storage pool",
      Provider: "Disk",
      WriteMode: "GUID",
      UseSsl: false,
      DiskDirectory: "./disk/",
      Compress: "None",
      EnableReadCaching: false,
    });
    console.log(response, "Storage pool created successfully");
  } catch (err) {
    console.log("Error creating Storage pool:", err);
  }
};

createStoragePool();

Read

To read an object by GUID, call GET /v1.0/tenants/[tenant-guid]/pools/[pool-guid]. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/pools/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const readStoragePool = async () => {
  try {
    const response = await storage.retrieveStoragePool(
      "4a931b31-a8a7-4b65-ab35-80e647a46ffd"
    );
    console.log(response, "Storage pool fetched successfully");
  } catch (err) {
    console.log("Error fetching Storage pool:", err);
  }
};

readStoragePool();

Read all

o read all objects, call GET /v1.0/tenants/[tenant-guid]/pools/. If the object exists, it will be returned as an array of JSON object in the response body

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/pools/' \
--header 'Authorization: ••••••'

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const readAllStoragePools = async () => {
  try {
    const response = await storage.retrieveStoragePools();
    console.log(response, "Storage pools fetched successfully");
  } catch (err) {
    console.log("Error fetching Storage pools:", err);
  }
};

readAllStoragePools();

Update

To update, call PUT /v1.0/tenants/[tenant-guid]/pools/{pool-guid} with the object properties using the Configuration server

curl --location --request PUT 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/encryptionkeys/00000000-0000-0000-0000-000000000000' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--data '{
     "GUID": "4a931b31-a8a7-4b65-ab35-80e647a46ffd",
      "Name": "My disk storage pool [updated]",
      "Provider": "Disk",
      "WriteMode": "GUID",
      "UseSsl": false,
      "DiskDirectory": "./disk/",
      "Compress": "None",
      "EnableReadCaching": false,
    }'

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const updateStoragePool = async () => {
  try {
    const response = await storage.updateStoragePool({
      GUID: "4a931b31-a8a7-4b65-ab35-80e647a46ffd",
      Name: "My disk storage pool [updated]",
      Provider: "Disk",
      WriteMode: "GUID",
      UseSsl: false,
      DiskDirectory: "./disk/",
      Compress: "None",
      EnableReadCaching: false,
    });
    console.log(response, "Storage pool updated successfully");
  } catch (err) {
    console.log("Error updating Storage pool:", err);
  }
};

updateStoragePool();

Delete

To delete an object by GUID, call DELETE /v1.0/tenants/[tenant-guid]/pools/[pool-guid].

curl --location --request DELETE 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/pools/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••' \

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const deleteStoragePool = async () => {
  try {
    const response = await storage.deleteStoragePool(
      "8d323640-eaf4-4fbf-a11a-84b89f74f776"
    );
    console.log(response, "Storage pool deleted successfully");
  } catch (err) {
    console.log("Error deleting Storage pool:", err);
  }
};

deleteStoragePool();

Check Existence

Note: the HEAD method can be used as an alternative to get to simply check the existence of the object. HEAD requests return either a 200/OK in the event the object exists, or a 404/Not Found if not. No response body is returned with a HEAD request.

curl --location --head 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/pools/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewStorageSdk } from "view-sdk";

const storage = new ViewStorageSdk(
  "00000000-0000-0000-0000-000000000000", //tenant Id
  "default", //access token
  "http://localhost:8001/" //endpoint
);

const existsStoragePool = async () => {
  try {
    const response = await storage.existsStoragePool(
      "4a931b31-a8a7-4b65-ab35-80e647a46ffd"
    );
    console.log(response, "Storage pool exists");
  } catch (err) {
    console.log("Error checking Storage pool:", err);
  }
};

existsStoragePool();