API Reference

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 string globally unique identifier for the object
  • TenantGUID string globally unique identifier for the tenant
  • PoolGUID string globally unique identifier for the storage pool used by the bucket
  • OwnerGUID string 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 -X PUT http://localhost:8001/v1.0/tenants/[tenant-guid]/buckets \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [accesskey]" \
     -d '
{
    "PoolGUID": "default",
    "Name": "testbucket",
    "RegionString": "us-west-1",
    "Versioning": true
}'

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:

{
    "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
}

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"
    },
    { ... }
]

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"
}

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.

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.