Using extended API with JavaScript

Initialization

npm i axios aws4-axios

import axios from 'axios';
import { aws4Interceptor } from 'aws4-axios';

const client = axios.create({
  baseURL: 'https://s3.coldstack.io'
})

client.interceptors.request.use(aws4Interceptor({
  region: 'us-east-1',
  service: 's3',
}, {
  accessKeyId: '...',
  secretAccessKey: '...',
}));

Getting extended list of buckets

const response = await client.get('/?extendedBuckets', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
    },
});

console.log(response.data)

Result

{
  "ListAllMyBucketsExtendedResult": {
    "PerPage": 10,
    "Page": 1,
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    },
    "Buckets": [
      {
        "Name": "bucket-1",
        "CreationDate": "2021-04-11T16:34:16.364Z",
        "ObjectsCount": "14",
        "ObjectsWithoutFoldersCount": "13"
      },
      {
        "Name": "bucket-2",
        "CreationDate": "2021-05-30T14:53:33.899Z",
        "ObjectsCount": "0",
        "ObjectsWithoutFoldersCount": "0"
      }
    ]
  }
}

Getting extended list of objects

const response = await client.get('/BUCKET?extendedObjects', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
        delimiter: '/',
        prefix: 'folder/nested-folder/',
    },
});

console.log(response.data)

Result

{
  "ListExtendedObjects": {
    "Name": "BUCKET",
    "PerPage": 10,
    "Page": 1,
    "Prefix": "folder/nested-folder/",
    "KeyCount": 2, // Количество результатов в данном ответе сервера
    "AvailableKeyCount": 2, // Количество файлов в этой папке
    "Delimiter": "/",
    "IsTruncated": false, // Урезан ли список файлов
    "Contents": [
      {
        "Key": "folder/nested-folder/15mb.random",
        "LastModified": "2021-08-12T22:14:53.608Z",
        "ETag": "\"bc71d03e01a1d931e15cf07bd0a90c2f-2\"",
        "Size": "15000000",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "application/octet-stream",
        "ACL": "private",
        "FileType": "file"
      },
      {
        "Key": "folder/nested-folder/icon.png",
        "LastModified": "2021-08-12T22:13:05.894Z",
        "ETag": "\"629e4d5c1d0086a8c833bef7f3427994\"",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "image/png",
        "ACL": "public-read",
        "FileType": "file"
      }
    ],
    "CommonPrefixes": [
      {
        "Prefix": "folder/nested-folder/other-nested-folder/",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "LastModified": "2021-08-12T22:13:05.894Z"
      }
    ]
  }
}

Get statistics

const response = await client.get('/?statistics', {
    params: { format: 'json' } },
);

console.log(response.data);

Result

{
  "Statistics": {
    "BucketsCount": 4,
    "ObjectsCount": 14,
    "UsedStorage": {
      "UsedStorageBytes": "286249388",
      "UsedStorageReadableQuantity": "286",
      "UsedStorageReadableUnit": "MB"
    },
    "Bandwidth": {
      "BandwidthBytes": "20159227",
      "BandwidthReadableQuantity": "20.2",
      "BandwidthReadableUnit": "MB"
    }
  }
}

Get bandwidth analytics

const response = await client.get('/?bandwidthAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);

Result

{
  "BandwidthAnalytics": {
    "Records": [
      {
        "Date": "2021-08-13",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      },
      {
        "Date": "2021-08-14",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      }
    ]
  }
}

Get storage usage analytics

const response = await client.get('/?storageAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);

Result

{
  "StorageUsageAnalytics": {
    "Records": [
      {
        "Timestamp": "2021-08-31T01:00:00.000Z",
        "UsedStorage": "15000000",
        "UsedStorageReadable": "15 MB"
      },
      {
        "Timestamp": "2021-08-31T02:00:00.000Z",
        "UsedStorage": "16000000",
        "UsedStorageReadable": "16 MB"
      }
    ]
  }
}

Rename bucket

await client({
  url: '/old-bucket-name',
  method: 'MOVE',
  headers: {
    'Destination': 'new-bucket-name',
  },
});

Rename a file

await client({
  url: '/old-bucket-name/file.txt',
  method: 'MOVE',
  headers: {
    'Destination': 'file-2.txt',
  },
});

Rename a folder

await client({
  url: '/old-bucket-name/folder/',
  method: 'MOVE',
  headers: {
    'Destination': 'folder-2/',
    'X-ColdStack-Prefix': 'true',
  },
});

Get Extended info about file (extended HeadObject)

await client({
  url: '/old-bucket-name/file?extendedInfo',
  method: 'GET',
  params: {
    format: 'json',
  },
});

Result

{
  "ObjectExtendedInfo": {
    "CacheControl": "...",
    "ContentDisposition": "...",
    "ContentEncoding": "...",
    "ContentLanguage": "...",
    "Expires": "...",
    "ContentType": "...",
    "FileType": "...",
    "ETag": "...",
    "Size": 1024,
    "SizeReadable": "1 KB",
    "LastModified": "...",
    "StorageClass": "...",
    "StorageClassReadable": "...",
    "Metadata": {
      "key": "value"
    },
    "ACL": "private" | "public-read",
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    }
  }
}

Check if user can upload

await client({
  url: '/?canUpload',
  method: 'GET',
});

Result

{
    "CanUpload": true
}

or

{
    "CanUpload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}

Check if user can download

await client({
  url: '/?canDownload',
  method: 'GET',
});

Result

{
    "CanDownload": true
}

or

{
    "CanDownload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}

Search files

await client({
  url: '/?searchFiles',
  method: 'GET',
  params: {
    "perPage": 10,
    "page": 1,
    "format": "json",
    "filename": "video"
  }
});

Result

{
  "SearchFilesResult": {
    "Query": {
      "perPage": 10,
      "page": 1
    },
    "Files": [
      {
        "Key": "videos/pres-video.mp4",
        "FileType": "video",
        "Bucket": "personal-files",
        "FileName": "pres-video.mp4"
      },
      {
        "Key": "other-files/videos-list.txt",
        "FileType": "file",
        "Bucket": "other-bucket",
        "FileName": "videos-list.txt"
      }
    ]
}