OBJECT STORAGE

Object Storage is a computer data storage architecture that manages data as objects as opposed to block storage which manages data as blocks within sectors and tracks. Object storage is commonly used to manage large amounts of unstructured data for example storing large datasets like photos, music, or files in online collaboration services.

Object Storage API commands allow creation, management and deletion of Object Storage devices as well as viewing Object Storage network data usage. Object Storage is fully S3-compliant allowing file and bucket management using existing S3 clients.

Get Object Storages

List all Object Storage devices on the account or those which the subaccount has permissions.

Request

GET /1.3/object-storage/

Normal response

HTTP/1.0 200 OK
{
  "object_storages": {
    "object_storage": [
      {
        "created": "2020-07-23T05:06:35Z",
        "description": "Example object storage",
        "name": "example-object-storage",
        "size": 250,
        "state": "started",
        "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
        "uuid": "06832a75-be7b-4d23-be05-130dc3dfd9e7",
        "zone": "uk-lon1"
      },
      {
        "created": "2020-07-23T05:06:35Z",
        "description": "App object storage",
        "name": "app-object-storage",
        "size": 500,
        "state": "started",
        "url": "https://app-data-storage.nl-ams1.upcloudobjects.com/",
        "uuid": "06636a75-ae9b-4d23-be06-260dc3ded8e0",
        "zone": "nl-ams1"
      }
    ]
  }
}

Create Object Storage

Used to create a new Object Storage device with a given name, size and location.

Request

POST /1.3/object-storage/
{
  "object_storage": {
    "name": "app-object-storage",
    "description": "App object storage",
    "zone": "nl-ams1",
    "access_key": "UCOBTMRABUTKMC2WF6BD",
    "secret_key": "NCAtWEblflr7HhimErIgRVNo48+x546VLm0azVcO",
    "size": 500
  }
}

Attributes

Attribute Accepted value Required Description
name 3-32 characters no Object Storage name, default is device UUID
description 1-255 characters no Short description for the Object Storage
zone A valid zone identifier yes The zone in which the server will be hosted, e.g. fi-hel1. See Zones.
access_key yes Access key used to identify user
secret_key yes Secret key used to authenticate user
size 250, 500, 1000 yes Object Storage size in gigabytes

Normal response

HTTP/1.0 201 OK
{
  "object_storage": {
    "name": "app-object-storage",
    "description": "App object storage",
    "zone": "nl-ams1",
    "size": 500
  }
}

Error responses

HTTP status Error code Description
400 Bad Request SIZE_INVALID The attribute size has an invalid value
400 Bad Request SIZE_MISSING The required attribute size is missing
400 Bad Request ACCESS_KEY_INVALID The attribute access_key has an invalid value
400 Bad Request ACCESS_KEY_MISSING The required attribute access_key is missing
400 Bad Request SECRET_KEY_INVALID The attribute secret_key has an invalid value
400 Bad Request SECRET_KEY_MISSING The required attribute secret_key is missing
400 Bad Request DESCRIPTION_INVALID The attribute description has an invalid value
400 Bad Request ZONE_MISSING The required attribute zone is missing
403 Forbidden OBJECT_STORAGE_FORBIDDEN No permission to access details of the specified Object Storage
404 Not Found OBJECT_STORAGE_NOT_FOUND Object Storage {uuid} does not exist
404 Not Found ZONE_NOT_FOUND The zone {zone} does not exist
409 Conflict NAME_INVALID The attribute name has an invalid value

Get Object Storage details

A request to get details about a specific Object Storage device by the given {uuid}.

Request

GET /1.3/object-storage/{uuid}

Normal response

HTTP/1.0 200 OK
{
  "object_storage": {
    "uuid": "063881d4-edc5-4102-8214-9b7e11edb9cb",
    "name": "app-object-storage",
    "description": "app-object-storage",
    "zone": "nl-ams1",
    "url": "https://063881d4-edc5-4102-8214-9b7e11edb9cb.os.upcloud.host/",
    "size": 500,
    "used_space": 0,
    "state": "started",
    "created": "2020-07-23T05:06:35Z"
  }
}

Modify Object Storage

Modify requests can be used to update the details of an Object Storage including description, access_key and secret_key.

Request

PATCH /1.3/object-storage/{uuid}
{
  "object_storage": {
    "description": "Example object storage",
    "access_key": "JT9WE882AZ548P5F1OZ2",
    "secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP"
  }
}

Attributes

Attribute Accepted value Required Description
description 1-255 characters no Short description for the Object Storage
access_key 4-255 characters yes if secret_key given Access key used to identify user
secret_key 8-255 characters yes if access_key given Secret key used to authenticate user
size 250, 500, 1000 no Size of Object Storage in gigabytes, can be increased but cannot be decreased

Normal response

HTTP/1.0 200 OK
{
  "object_storage": {
    "uuid": "063881d4-edc5-4102-8214-9b7e11edb9cb",
    "name": "Example object storage",
    "zone": "fi-hel1",
    "url": "https://063881d4-edc5-4102-8214-9b7e11edb9cb.os.upcloud.host/",
    "size": 500,
    "used_space": 42,
    "state": "started",
    "created": "2020-07-23T05:06:35Z"
  }
}

Error responses

HTTP status Error code Description
400 Bad Request SIZE_INVALID The attribute size has an invalid value
400 Bad Request SIZE_INVALID Size can not be decreased
400 Bad Request ACCESS_KEY_INVALID The attribute access_key has an invalid value
400 Bad Request SECRET_KEY_INVALID The attribute secret_key has an invalid value
400 Bad Request DESCRIPTION_INVALID The attribute description has an invalid value
403 Forbidden OBJECT_STORAGE_FORBIDDEN No permission to access details of the specified Object Storage
404 Not Found OBJECT_STORAGE_NOT_FOUND Object Storage {uuid} does not exist

Delete Object Storage

Object Storage devices can be deleted using the following API request. Note that deleting the storage will permanently delete any data on the device and which cannot be reverted.

Request

DELETE /1.3/object-storage/{uuid}

Normal response

HTTP/1.0 204 No Content

Error responses

HTTP status Error code Description
403 Forbidden OBJECT_STORAGE_FORBIDDEN No permission to access details of the specified Object Storage
404 Not Found OBJECT_STORAGE_NOT_FOUND Object Storage {uuid} does not exist

Get Object Storage network statistics

The network usage of an Object Storage device is metered and can be reviewed using the statistics request.

Request

GET /1.3/object-storage/{uuid}/stats/network/?from={date-time}

Parameters

Statistics queries can be filtered and arranged using a number of query parameters.

Key Value Required Description
from {date-time} 2020-01-01T00%3A00%3A00Z yes Beginning of time range; RFC 3339 timestamp or negative integer noting hours from current time
to {date-time} 2020-12-31T00%3A00%3A00Z End of time range, default is current time, format as in from
interval {integer} >= 1, <= time range hours Grouping results by number of hours, default: 1
bucket array[string] Filter results by bucket name
filename array[string] Filter results by filename
method array[string] GET, POST, PATCH, PUT, DELETE Filter results by HTTP method
status array[integer] HTTP status codes Filter results by HTTP status
group_by array[string] bucket, filename, method, status Group results by specified properties
order_by array[string] timestamp, bytes_received, bytes_transmitted, requests, bucket, filename, method, status Order results by specified properties, default ascending timestamp, descending with - prefix
limit {integer} Limit to specified number of results

Normal response

HTTP/1.0 200 OK
{
  "stats": {
    "stat": [
      {
        "timestamp": "2020-07-21T09:20:25.988Z",
        "bucket": "string",
        "filename": "string",
        "method": "GET",
        "status": 0,
        "bytes_received": 0,
        "bytes_transmitted": 0,
        "requests": 0
      }
    ]
  }
}

Error responses

HTTP status Error code Description
403 Forbidden OBJECT_STORAGE_FORBIDDEN No permission to access details of the specified Object Storage
404 Not Found OBJECT_STORAGE_NOT_FOUND Object Storage {uuid} does not exist

Manage buckets and files

Managing an object storage's buckets and file objects is done via the S3 compliant API. The endpoint URL can be found in the API response. Use they access key & secret key that you set when creating the object storage.

You can create your own S3 client or use any of the S3-compliant libraries/software available online. For example, s3cmd is a good command-line client for getting started with S3.