Buckets

Object Overview

Buckets are virtual repositories for storing objects within View object storage services.

Endpoint, URL, and Supported Methods

Buckets are managed via the configuration server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/buckets or through the S3 compatible API.

By default, the storage server is accessible on port 8001 for the View REST API, and 8002 for the S3-compatible API.

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following structure:

{
    "GUID": "example-data-bucket",
    "TenantGUID": "default",
    "PoolGUID": "default",
    "OwnerGUID": "default",
    "Category": "Data",
    "Name": "example-data-bucket",
    "RegionString": "us-west-1",
    "Versioning": true,
    "MaxMultipartUploadSeconds": 604800,
    "LastAccessUtc": "2024-07-10T05:09:32.000000Z",
    "CreatedUtc": "2024-07-10T05:09:32.000000Z"
}

Properties:

GUID GUID globally unique identifier for the object
TenantGUID GUID globally unique identifier for the tenant
PoolGUID GUID globally unique identifier for the storage pool used by the bucket
OwnerGUID GUID globally unique identifier for the user that owns the bucket
Category enum category enumeration for the bucket, valid values are Data, Metadata, and Embeddings
Name string name of the object
RegionString string the AWS region to use for this bucket
Versioning bool enable or disable versioning
MaxMultipartUploadSeconds int the maximum number of seconds before expiring unfinished multipart uploads
LastAccessUtc datetime timestamp from last access, in UTC time
CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/buckets with the following properties using the storage server: PoolGUID Name RegionString Versioning

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "PoolGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "testbucket [ASH]",
    "RegionString": "us-west-1",
    "Versioning": true
}'

import { ViewStorageSdk } from "view-sdk";

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

const createBucket = async () => {
  try {
    const response = await storage.createBucket({
      PoolGUID: "00000000-0000-0000-0000-000000000000",
      Name: "testbucket [ASH1]",
      RegionString: "us-west-1",
      Versioning: true,
    });
    console.log(response, "Bucket created successfully");
  } catch (err) {
    console.log("Error creating bucket:", err);
  }
};

Enumerate

Enumerate objects within a bucket by using GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]. The resultant object will appear as shown below. Refer to the Objects page for details about object metadata:ii

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-27T02:25:15.818060Z",
        "End": "2024-10-27T02:25:15.940821Z",
        "TotalMs": 122.76,
        "Messages": {}
    },
    "MaxResults": 1000,
    "IterationsRequired": 1,
    "Statistics": {
        "Objects": 45,
        "Bytes": 59685665
    },
    "SharedPrefixes": [],
    "Objects": [
        {
            "GUID": "6c04d8f1-5921-480f-a0cb-d57cc57f1d29",
            "TenantGUID": "default",
            "NodeGUID": "05a93a0c-bab0-4442-8444-a5863fabc9ec",
            "PoolGUID": "default",
            "BucketGUID": "example-data-bucket",
            "OwnerGUID": "default",
            "DataCatalogDocumentGUID": "d4b523bb-f1ac-4361-96c7-d1e7c69476ec",
            "DataFlowRequestGUID": "86caef5d-7380-442d-8103-bd94154bdad9",
            "Key": "2.pdf",
            "Version": "2",
            "IsLatest": true,
            "IsDeleteMarker": false,
            "IsLocal": true,
            "ContentType": "application/pdf",
            "DocumentType": "Unknown",
            "SourceUrl": "http://dcc249eaaf06:8001/v1.0/tenants/default/buckets/example-data-bucket/objects/2.pdf",
            "MD5Hash": "F92FA118E289B43D861957B6767F08F0",
            "SHA1Hash": "B307A7B0980128888DDDFC9AD5B750779C0F196B",
            "SHA256Hash": "086478AB97970F80C30A495F6505539063FB6461F1A6AC7D053F821F97107B94",
            "IsEncrypted": false,
            "WriteMode": "GUID",
            "CompressionType": "None",
            "ContentLength": 526692,
            "CompressedLength": 0,
            "EncryptedLength": 0,
            "CompressionRatioPercent": 0,
            "CompressionRatioX": 0,
            "LastAccessUtc": "2024-10-25T15:49:59.000000Z",
            "LastModifiedUtc": "2024-10-25T15:49:59.000000Z",
            "CreatedUtc": "2024-10-25T15:49:59.000000Z",
            "Owner": {
                "GUID": "default",
                "TenantGUID": "default",
                "FirstName": "Default",
                "LastName": "User",
                "FullName": "Default User",
                "Notes": "Default password is password",
                "Email": "[email protected]",
                "PasswordSha256": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
                "Active": true,
                "CreatedUtc": "2024-07-10T05:09:31.000000Z"
            }
        },
        { ... }
    ],
    "DeleteMarkers": [],
    "EndOfResults": true,
    "RecordsRemaining": 0
}

import { ViewStorageSdk } from "view-sdk";

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

const enumerateBuckets = async () => {
  try {
    const response = await storage.enumerateBucketObjects(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Buckets fetched successfully");
  } catch (err) {
    console.log("Error fetching buckets:", err);
  }
};

enumerateBuckets();

List Buckets

To list the available buckets, call GET /v1.0/tenants/[tenant-guid]/buckets. An array is returned containing the list of available buckets.

[
    {
        "GUID": "example-data-bucket",
        "TenantGUID": "default",
        "PoolGUID": "default",
        "OwnerGUID": "default",
        "Category": "Data",
        "Name": "example-data-bucket",
        "RegionString": "us-west-1",
        "Versioning": true,
        "MaxMultipartUploadSeconds": 604800,
        "LastAccessUtc": "2024-07-10T05:09:32.000000Z",
        "CreatedUtc": "2024-07-10T05:09:32.000000Z"
    },
    { ... }
]

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

import { ViewStorageSdk } from "view-sdk";

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

const readAllBuckets = async () => {
  try {
    const response = await storage.retrieveAllBuckets();
    console.log(response, "Buckets fetched successfully");
  } catch (err) {
    console.log("Error fetching buckets:", err);
  }
};

readAllBuckets();

Read Bucket Metadata

To read a bucket's metadata by GUID, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?md. 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.

{
    "GUID": "example-data-bucket",
    "TenantGUID": "default",
    "PoolGUID": "default",
    "OwnerGUID": "default",
    "Category": "Data",
    "Name": "example-data-bucket",
    "RegionString": "us-west-1",
    "Versioning": true,
    "MaxMultipartUploadSeconds": 604800,
    "LastAccessUtc": "2024-07-10T05:09:32.000000Z",
    "CreatedUtc": "2024-07-10T05:09:32.000000Z"
}

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?md=null' \
--header 'Authorization: ••••••' \
--data ''

import { ViewStorageSdk } from "view-sdk";

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

const retrieveBucketMetadata = async () => {
  try {
    const response = await storage.retrieveBucketMetadata(
      "ca432dea-6937-4ebe-a791-f09c16eacfdf"
    );
    console.log(response, "Bucket fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket:", err);
  }
};

retrieveBucketMetadata();

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.

Update

To update a bucket by GUID, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid].

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: application/json' \
--data '{
    "Name": "testbucket2",
    "RegionString": "us-west-1",
    "Versioning": true,
    "RetentionMinutes": 1
}'

import { ViewStorageSdk } from "view-sdk";

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


const updateBucket = async () => {
  try {
    const response = await storage.updateBucket({
      GUID: "ca432dea-6937-4ebe-a791-f09c16eacfdf",
      Name: "testbucket [ASH1] [updated]",
      RegionString: "us-west-1",
      Versioning: true,
      MaxMultipartUploadSeconds: 604800,
    });
    console.log(response, "Bucket updated successfully");
  } catch (err) {
    console.log("Error updating bucket:", err);
  }
};

updateBucket();

Delete

To delete a bucket by GUID, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]. If the bucket is not empty, a 400 will be returned.

curl --location --request DELETE 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: Bearer default' \
--data ''

import { ViewStorageSdk } from "view-sdk";

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

const deleteBucket = async () => {
  try {
    const response = await storage.deleteBucket(
      "ca432dea-6937-4ebe-a791-f09c16eacfdf"
    );
    console.log(response, "Bucket deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket:", err);
  }
};

deleteBucket();

Create Bucket Tags

To create tags of a bucket by GUID, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?tags.

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?tags=null' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: application/json' \
--data '[
    {
        "Key": "foo",
        "Value": "bar"
    }
]'

import { ViewStorageSdk } from "view-sdk";

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

const createBucketTags = async () => {
  try {
    const response = await storage.createBucketTags(
      "00000000-0000-0000-0000-000000000000",
      [
        {
          Key: "test",
          Value: "test",
        },
      ]
    );
    console.log(response, "Bucket tags created successfully");
  } catch (err) {
    console.log("Error creating bucket tags:", err);
  }
};
createBucketTags();

Retrieve Bucket Tags

To retrieve tags of a bucket by GUID, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?tags. If the bucket is not empty, a 400 will be returned.

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?tags=null' \
--header 'Authorization: Bearer default'

import { ViewStorageSdk } from "view-sdk";

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

const retrieveBucketTags = async () => {
  try {
    const response = await storage.retrieveBucketTags(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Bucket tags fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket tags:", err);
  }
};

retrieveBucketTags();

Delete Bucket Tags

To delete tags of a bucket by GUID, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?tags. If the bucket is not empty, a 400 will be returned.

curl --location --request DELETE 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?tags=null' \
--header 'Authorization: Bearer default' \
--data ''

import { ViewStorageSdk } from "view-sdk";

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

const deleteBucketTags = async () => {
  try {
    const response = await storage.deleteBucketTags(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Bucket tags deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket tags:", err);
  }
};

deleteBucketTags();

Create Bucket ACL

To create acl of a bucket by GUID, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?acl. If the bucket is not empty, a 400 will be returned.

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?acl=null' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Owner": {
        "GUID": "default",
        "TenantGUID": "default",
        "FirstName": "Default",
        "LastName": "User",
        "FullName": "Default User",
        "Notes": "Default password is password",
        "Email": "[email protected]",
        "Active": true,
        "CreatedUtc": "2024-08-06T16:30:09.495213Z"
    },
    "Users": [
        {
            "GUID": "default",
            "TenantGUID": "default",
            "FirstName": "Default",
            "LastName": "User",
            "FullName": "Default User",
            "Notes": "Default password is password",
            "Email": "[email protected]",
            "Active": true,
            "CreatedUtc": "2024-08-06T16:30:09.495213Z"
        }
    ],
    "Entries": [
        {
            "GUID": "default",
            "TenantGUID": "default",
            "BucketGUID": "example-data-bucket",
            "OwnerGUID": "default",
            "UserGUID": "default",
            "CanonicalUser": "",
            "EnableRead": true,
            "EnableReadAcp": true,
            "EnableWrite": true,
            "EnableWriteAcp": true,
            "FullControl": true,
            "CreatedUtc": "2024-08-06T16:30:09.643691Z"
        }
    ]
}'

import { ViewStorageSdk } from "view-sdk";

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

const createBucketACL = async () => {
  try {
    const response = await storage.createBucketACL(
      "00000000-0000-0000-0000-000000000000",
      {
        Owner: {
          GUID: "default",
          TenantGUID: "default",
          FirstName: "Default",
          LastName: "User",
          FullName: "Default User",
          Notes: "Default password is password",
          Email: "[email protected]",
          Active: true,
          CreatedUtc: "2024-08-06T16:30:09.495213Z",
        },
        Users: [
          {
            GUID: "default",
            TenantGUID: "default",
            FirstName: "Default",
            LastName: "User",
            FullName: "Default User",
            Notes: "Default password is password",
            Email: "[email protected]",
            Active: true,
            CreatedUtc: "2024-08-06T16:30:09.495213Z",
          },
        ],
        Entries: [
          {
            GUID: "default",
            TenantGUID: "default",
            BucketGUID: "example-data-bucket",
            OwnerGUID: "default",
            UserGUID: "default",
            CanonicalUser: "",
            EnableRead: true,
            EnableReadAcp: true,
            EnableWrite: true,
            EnableWriteAcp: true,
            FullControl: true,
            CreatedUtc: "2024-08-06T16:30:09.643691Z",
          },
        ],
      }
    );
    console.log(response, "Bucket ACL created successfully");
  } catch (err) {
    console.log("Error creating bucket ACL:", err);
  }
};

createBucketACL();

Read Bucket ACL

To read acl of a bucket by GUID, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?acl. If the bucket is not empty, a 400 will be returned.

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?acl=null' \
--header 'Authorization: Bearer default' \
--data ''

import { ViewStorageSdk } from "view-sdk";

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

const retrieveBucketACL = async () => {
  try {
    const response = await storage.retrieveBucketACL(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Bucket ACL fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket ACL:", err);
  }
};

retrieveBucketACL();

Delete Bucket ACL

To delete acl of a bucket by GUID, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]?acl. If the bucket is not empty, a 400 will be returned.

curl --location --request DELETE 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000?acl=null' \
--header 'Authorization: Bearer default' \
--data ''

import { ViewStorageSdk } from "view-sdk";

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

const deleteBucketACL = async () => {
  try {
    const response = await storage.deleteBucketACL(
      "00000000-0000-0000-0000-000000000000"
    );
    console.log(response, "Bucket ACL deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket ACL:", err);
  }
};

deleteBucketACL();