API Reference

Objects

This page covers configuration and management of View objects.

Object Overview

Objects are files uploaded to buckets within View storage server, either by the View standard API or S3 API.

Endpoint, URL, and Supported Methods

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

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

Objects contain metadata about the file that has been uploaded. A fully populated storage pool using local disk is shown below.:

{
    "GUID": "74ee4b8a-188e-4a73-8a42-3b7fb1ccb5e0",
    "TenantGUID": "default",
    "NodeGUID": "05a93a0c-bab0-4442-8444-a5863fabc9ec",
    "PoolGUID": "default",
    "BucketGUID": "example-data-bucket",
    "OwnerGUID": "default",
    "Key": "1.pdf",
    "Version": "2",
    "IsLatest": true,
    "IsDeleteMarker": false,
    "IsLocal": true,
    "ContentType": "application/pdf",
    "DocumentType": "Pdf",
    "SourceUrl": "http://dcc249eaaf06:8001/v1.0/tenants/default/buckets/example-data-bucket/objects/1.pdf",
    "MD5Hash": "5DB1D1E8426F5381BEAB883076033F9E",
    "SHA1Hash": "09A31789FD9797C311B63C4D8EE9CC103B104066",
    "SHA256Hash": "F36DFAC021555765E6A617481613AB047850B8AB7D84DBD7870DF00CF6A1796B",
    "IsEncrypted": false,
    "WriteMode": "GUID",
    "CompressionType": "None",
    "ContentLength": 1686283,
    "CompressedLength": 0,
    "EncryptedLength": 0,
    "CompressionRatioPercent": 0,
    "CompressionRatioX": 0,
    "LastAccessUtc": "2024-10-25T15:49:58.000000Z",
    "LastModifiedUtc": "2024-10-25T15:49:58.000000Z",
    "CreatedUtc": "2024-10-25T15:49:58.000000Z"
}

Properties:

  • GUID GUID globally unique identifier for the object
  • TenantGUID GUID globally unique identifier for the tenant
  • NodeGUID GUID globally unique identifier for the node where the object was written
  • PoolGUID GUID globally unique identifier for the storage pool holding the object
  • BucketGUID GUID globally unique identifier for the bucket holding the object
  • OwnerGUID GUID globally unique identifier for the user that wrote the object
  • Key string the key for the object, i.e. the filename
  • Version string the version of the object
  • IsLatest bool boolean indicating if this version is the latest version of the object
  • IsDeleteMarker bool boolean indicating whether or not the object is a delete marker
  • IsLocal bool boolean indicating whether or not the object contents are stored locally
  • ContentType string the content type of the object
  • DocumentType string the document type of the object
  • SourceUrl string the source URL for accessing the object
  • MD5Hash string the MD5 hash, as a hexadecimal string
  • SHA1Hash string the SHA1 hash, as a hexadecimal string
  • SHA256Hash string the SHA256 hash, as a hexadecimal string
  • IsEncrypted bool boolean indicating if the object is encrypted at rest
  • WriteMode enum the write mode used to write the object; valid values are GUID, Key
  • CompressionType enum the compression type applied to the object
  • ContentLength long the content length of the object
  • CompressedLength long the compressed length of the object
  • EncryptedLength long the encrypted length of the object
  • CompressionRatioPercent decimal the compression ratio for the object
  • CompressionRatioX decimal the compression ratio, represented as a multiplier, for the object
  • LastAccessUtc datetime timestamp from last access, in UTC time
  • LastModifiedUtc datetime timestamp from last modification, in UTC time
  • CreatedUtc datetime timestamp from creation, in UTC time

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key] with the body of the object as the request body.

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/hello.temp' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: text/plain' \
--data 'Hello, world!'

import { ViewStorageSdk } from "view-sdk";

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

const writeObject = async () => {
  try {
    const response = await storage.writeObject(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp",
      "testobject"
    );
    console.log(response, "Object written successfully");
  } catch (err) {
    console.log("Error writing object:", err);
  }
};

Read object data

To read an object by key, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]. This will return the body of the object. If the object does not exist, a 404 will be returned with a NotFound error response.

Hello, world!

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/testsdk.temp' \
--header 'Authorization: Bearer ******' 

import { ViewStorageSdk } from "view-sdk";

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

const readObjectData = async () => {
  try {
    const response = await storage.retrieveObjectData(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp"
    );
    console.log(response, "Object data read successfully");
  } catch (err) {
    console.log("Error reading object data:", err);
  }
};

readObjectData();

To read the metadata of an object, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?md. This will return the JSON object below, which contains the properties described above. If the object does not exist, a 404 will be returned with a NotFound error response.

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.

Read object data in range

To read an object by key in range, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]with Range header. This will return the body of the object. If the object does not exist, a 404 will be returned with a NotFound error response.

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/testsdk.temp' \
--header 'Range: bytes=2-3' \
--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 retrieveObjectDataInRange = async () => {
  try {
    const response = await storage.retrieveObjectDataInRange(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp",
      "bytes=1-3"
    );
    console.log(response, "Object data in range read successfully");
  } catch (err) {
    console.log("Error reading object data in range:", err);
  }
};

retrieveObjectDataInRange();

Read object metadata

To read an object by key in range, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?md This will return the body of the object. If the object does not exist, a 404 will be returned with a NotFound` error response.

curl --location 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/hello.json?md=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 retrieveMetadata = async () => {
  try {
    const response = await storage.retrieveObjectMetadata(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp"
    );
    console.log(response, "Metadata fetched successfully");
  } catch (err) {
    console.log("Error fetching metadata:", err);
  }
};

retrieveMetadata();

Write Expiration

To expite an object on a date by object key, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?expirationwith ExpirationUtc in body. This will return the body of the object. If the object does not exist, a 404 will be returned with a NotFound error response.

curl --location --request PUT 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/testsdk.temp?expiration=null' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: application/json' \
--data '{
    "ExpirationUtc": "2026-09-15T00:00:00.000001Z"
}'

import { ViewStorageSdk } from "view-sdk";

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

const writeObjectExpiration = async () => {
  try {
    const response = await storage.writeObjectExpiration(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp",
      {
        ExpirationUtc: "2025-08-08T10:00:00Z",
      }
    );
    console.log(response, "Object expiration written successfully");
  } catch (err) {
    console.log("Error writing object expiration:", err);
  }
};

writeObjectExpiration();

Delete

To delete an object by key, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]. If bucket versioning is enabled, a delete marker will be added, otherwise, the object will be deleted.

curl --location --request DELETE 'http://view.homedns.org:8001/v1.0/tenants/00000000-0000-0000-0000-000000000000/buckets/00000000-0000-0000-0000-000000000000/objects/hello.json' \
--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 deleteObject = async () => {
  try {
    const response = await storage.deleteObject(
      "00000000-0000-0000-0000-000000000000",
      "testsdk.temp"
    );
    console.log(response, "Object deleted successfully");
  } catch (err) {
    console.log("Error deleting object:", err);
  }
};

deleteObject();;

Create Object Tags

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

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

import { ViewStorageSdk } from "view-sdk";

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

const writeTagForObject = async () => {
  try {
    const response = await storage.createObjectTags(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "hello.json", //object key
      [
        {
          Key: "hello",
          Value: "My first key!",
        },
      ]
    );
    console.log(response, "Tag written for object successfully");
  } catch (err) {
    console.log("Error writing tag for object:", err);
  }
};

writeTagForObject();

Retrieve Object Tags

To retrieve tags of a object by key, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?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/objects/hello.json?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 retrieveObjectTags = async () => {
  try {
    const response = await storage.retrieveObjectTags(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "hello.json", //object key
    );
    console.log(response, "Object tags fetched successfully");
  } catch (err) {
    console.log("Error fetching object tags:", err);
  }
};

retrieveObjectTags();

Delete Bucket Tags

To delete tags of a object by key, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?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/objects/hello.json?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 deleteObjectTags = async () => {
  try {
    const response = await storage.deleteObjectTags(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "hello.json", //object key
    );
    console.log(response, "Object tags deleted successfully");
  } catch (err) {
    console.log("Error deleting object tags:", err);
  }
};

deleteObjectTags();

Create Object ACL

To create acl of a object by key, call PUT /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?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/objects/testsdk.temp?acl=null' \
--header 'Authorization: Bearer default' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Owner": {
        "GUID": "00000000-0000-0000-0000-000000000000",
        "TenantGUID": "00000000-0000-0000-0000-000000000000",
        "FirstName": "Default",
        "LastName": "User",
        "FullName": "Default User",
        "Notes": "Default password is password",
        "Email": "[email protected]",
        "Active": true,
        "CreatedUtc": "2024-08-06T16:40:20.223290Z"
    },
    "Entries": []
}'

import { ViewStorageSdk } from "view-sdk";

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

const createObjectACL = async () => {
  try {
    const response = await storage.createObjectACL(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "testsdk.temp",//object key
       {
          "Owner": {
              "GUID": "00000000-0000-0000-0000-000000000000",
              "TenantGUID": "00000000-0000-0000-0000-000000000000",
              "FirstName": "Default",
              "LastName": "User",
              "FullName": "Default User",
              "Notes": "Default password is password",
              "Email": "[email protected]",
              "Active": true,
              "CreatedUtc": "2024-08-06T16:40:20.223290Z"
          },
          "Entries": []
      }
    );
    console.log(response, "Object ACL created successfully");
  } catch (err) {
    console.log("Error creating object ACL:", err);
  }
};

createObjectACL();

Read ObjectACL

To read acl of a object by key, call GET /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?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/objects/hello.json?acl=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 readObjectACL = async () => {
  try {
    const response = await storage.retrieveObjectACL(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "testsdk.temp",//object key
    );
    console.log(response, "Object ACL fetched successfully");
  } catch (err) {
    console.log("Error fetching object ACL:", err);
  }
};

readObjectACL();

Delete Bucket ACL

To delete acl of a bucket by GUID, call DELETE /v1.0/tenants/[tenant-guid]/buckets/[bucket-guid]/objects/[key]?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/objects/hello.json?acl=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 deleteObjectACL = async () => {
  try {
    const response = await storage.deleteObjectACL(
      "00000000-0000-0000-0000-000000000000", //bucket id
      "testsdk.temp",//object key
    );
    console.log(response, "Object ACL deleted successfully");
  } catch (err) {
    console.log("Error deleting object ACL:", err);
  }
};

deleteObjectACL();