API Reference
Start typing to search…

Buckets

This page covers configuration and management of View bucket objects.

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const createBucket = async () => {
  try {
    const response = await api.bucket.create({
      PoolGUID: "<pool-guid>",
      Name: "testbucket",
      RegionString: "us-west-1",
      Versioning: true,
    });
    console.log(response, "Bucket created successfully");
  } catch (err) {
    console.log("Error creating bucket:", err);
  }
};

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def createBucket():
    bucket = storage.Bucket.create(
        PoolGUID="<pool-guid>",
        Name="testbucket",
        RegionString="us-west-1",
        Versioning=True
    )
    print(bucket)

createBucket()

List Objects

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

curl --location 'http://ampere.view.io:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••' \
--data ''
import { ViewStorageSdk } from "view-sdk";

const api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const retrieveBucketObjects = async () => {
  try {
    const response = await api.bucket.readObject(
      "<bucket-guid>"
    );
    console.log(response, "Buckets fetched successfully");
  } catch (err) {
    console.log("Error fetching buckets:", err);
  }
};

retrieveBucketObjects();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def readAllObjects():
    objects = storage.Bucket.list_objects("<bucket-guid>")
    print(objects)

readAllObjects()

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

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

readAllBuckets();
import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def readAllBuckets():
    buckets = storage.Bucket.list_buckets()
    print(buckets)

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const retrieveBucketMetadata = async () => {
  try {
    const response = await api.bucket.readMetadata(
      "<bucket-guid>"
    );
    console.log(response, "Bucket fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket:", err);
  }
};

retrieveBucketMetadata();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def readBucketMetadata():
    bucket = storage.Bucket.retrieve_metadata("<bucket-guid>")
    print(bucket)

readBucketMetadata()

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);


const updateBucket = async () => {
  try {
    const response = await api.bucket.update({
      GUID: "<bucket-guid>",
      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();
import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def updateBucket():
    bucket = storage.Bucket.update(
        "<bucket-guid>",
        Name="testbucket",
        RegionString="us-west-1",
        Versioning=True
    )
    print(bucket)

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const deleteBucket = async () => {
  try {
    const response = await api.bucket.delete(
      "<bucket-guid>"
    );
    console.log(response, "Bucket deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket:", err);
  }
};

deleteBucket();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def deleteBucket():
    bucket = storage.Bucket.delete("<bucket-guid>")
    print(bucket)

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

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

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def createBucketTags():
    bucket = storage.BucketTags.create("<bucket-guid>",
        [
            {"Key": "Name", "Value": "testbucket"},
        ]
    )
    print(bucket)

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const retrieveBucketTags = async () => {
  try {
    const response = await api.bucket.readTags(
      "<bucket-guid>"
    );
    console.log(response, "Bucket tags fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket tags:", err);
  }
};

retrieveBucketTags();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def readBucketTag():
    bucket = storage.BucketTags.retrieve("<bucket-guid>")
    print(bucket)

readBucketTag()

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const deleteBucketTags = async () => {
  try {
    const response = await api.bucket.deleteTags(
      "<bucket-guid>"
    );
    console.log(response, "Bucket tags deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket tags:", err);
  }
};

deleteBucketTags();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def deleteBucketTag():
    bucket = storage.BucketTags.delete("<bucket-guid>")
    print(bucket)

deleteBucketTag()

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const createBucketACL = async () => {
  try {
    const response = await api.bucket.createACL(
      "<bucket-guid>",
      {
        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();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def createBucketACL():
    bucket = storage.BucketACL.create("<bucket-guid>",
    {
          "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"
        }
        ]
    }
    )
    print(bucket)

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const retrieveBucketACL = async () => {
  try {
    const response = await api.bucket.readACL(
      "<bucket-guid>"
    );
    console.log(response, "Bucket ACL fetched successfully");
  } catch (err) {
    console.log("Error fetching bucket ACL:", err);
  }
};

retrieveBucketACL();

import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def readBucketACL():
    bucket = storage.BucketACL.retrieve("<bucket-guid>")
    print(bucket)

readBucketACL()

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 api = new ViewStorageSdk(
  "http://localhost:8001/", //endpoint
  "<tenant-guid>", //tenant Id
  "default" //access key
);

const deleteBucketACL = async () => {
  try {
    const response = await api.bucket.deleteACL(
      "<bucket-guid>"
    );
    console.log(response, "Bucket ACL deleted successfully");
  } catch (err) {
    console.log("Error deleting bucket ACL:", err);
  }
};

deleteBucketACL();
import view_sdk
from view_sdk import storage

sdk = view_sdk.configure( access_key="default",base_url="localhost", tenant_guid= "<tenant-guid>")

def deleteBucketACL():
    bucket = storage.BucketACL.delete("<bucket-guid>")
    print(bucket)

deleteBucketACL()