How to manage UpCloud Object Storage via API

If your project or application has the need to handle large amounts of unstructured data, you should make use of object storage. It’s a computer data storage architecture that manages data as objects as opposed to block storage which manages data as blocks within sectors and tracks. As such, object storage is commonly used for storing large datasets like photos on Facebook, songs on Spotify, or files in online collaboration services.

The secure and redundancy ensured UpCloud Object Storage is the perfect place to store any data for your needs. Thanks to the S3-compatible and programmable interface, you have a host of options for existing tools and code implementations to make quick work of integrating Object Storage with your application.

Test hosting on UpCloud!

Using the UpCloud API

In this guide, we’ll show you the available API requests that can be used to create, manage and delete Object Storage devices as well as how to proceed after you’ve created your first Object Storage.

Note that accessing your UpCloud account via the API requires that you’ve enabled API permissions. If you are not yet familiar with the UpCloud API, we would suggest taking a quick look at our guide to getting started with UpCloud API to set up your API user account and access rights.

Getting details on Object Storage

There are two simple API requests that can be used to query information about your Object Storages, a general list of all requests and a call to pull information about a specific Object Storage.

Get all Object Storages

This request is used to list all Object Storage devices on the account or those for which the user has permissions if using a subaccount. Use the following GET request to list your Object Storages.

Request

GET /1.3/object-storage/

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": 500,
        "state": "started",
        "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
        "uuid": "06832a75-be7b-4d23-be05-130dc3dfd9e7",
        "zone": "uk-lon1"
      }
    ]
  }
}

Get Object Storage details

If you know the UUID of a specific Object Storage, you can get details about that Object Storage by adding the UUID to your API request URL as shown below.

Request

GET /1.3/object-storage/{uuid}

Response

HTTP/1.0 201 OK
{
  "object_storage": {
     "created": "2020-07-23T05:06:35Z",
     "description": "Example object storage",
     "name": "example-object-storage",
     "size": 500,
     "state": "started",
     "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
     "used_space": 0,
     "uuid": "06832a75-be7b-4d23-be05-130dc3dfd9e7",
     "zone": "uk-lon1"
  }
}

Creating new Object Storage

You can create a new Object Storage device by using the following API request. You will need to define at least the location and storage size for your new Object Storage by setting the zone and size attributes. This can be done for example in JSON format in the API request body.

You also need to set the access_key and secret_key which will be used to authenticate your access to the Object Storage when using an S3 client. These can be anything between 8 and 255 characters long.

Additionally, you may differentiate your Object Storage by setting the name and description attributes as shown in the example below.

Request

POST /1.3/object-storage/

Body

{
  "object_storage": {
    "name": "data-object-storage",
    "description": "data-object-storage",
    "zone": "nl-ams1",
    "access_key": "JT9WE882AZ548P5F1OZ2",
    "secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP",
    "size": 500
  }
}

Response

On successful request, you’ll get a response showing the details of your new Object Storage. The response will also include the url and uuid attributes which you’ll need for accessing the storage or making changes to it via the API,

HTTP/1.0 201 OK
{
   "object_storage": {
      "created": "2020-07-23T05:06:35Z",
      "description": "data-object-storage",
      "name": "data-object-storage",
      "size": 500,
      "state": "started",
      "url": "https://data-object-storage.nl-ams1.upcloudobjects.com/",
      "used_space": 0,
      "uuid": "06d42e69-b1c4-4543-8f9f-df5fc7712c04",
      "zone": "nl-ams1"
   }
}

Modifying Object Storage

It’s also possible to make some changes to your Object Storage after creation. You have the possibility to change the following attributes.

AttributeAccepted valueDescription
description1-255 charactersShort description for the Object Storage
access_key3-255 charactersAccess key used to identify user
secret_key8-255 charactersSecret key used to authenticate user
size2505001000Size of Object Storage in gigabytes, can be increased but cannot be decreased

Request

Then used an API request like the example below. Replace the uuid with the unique identifier of the Object Storage you wish to modify.

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

Normal response
If the changes were successful, you’ll get a response confirming the new details.

HTTP/1.0 200 OK
{
  "object_storage": {
     "created": "2020-07-23T05:06:35Z",
     "description": "Example object storage",
     "name": "example-object-storage",
     "size": 1000,
     "state": "started",
     "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
     "used_space": 0,
     "uuid": "06832a75-be7b-4d23-be05-130dc3dfd9e7",
     "zone": "uk-lon1"
  }
}

As mentioned, the Object Storage size can be scaled up with a simple API call which will then increase the allocated quota to the new requested amount. The operation may take a moment during which the Object Storage will be in maintenance mode as indicated by the state attribute.

Note that the Object Storage size can only be increased, decreasing the storage size is not supported.

Deleting Object Storage

Object Storage devices can be deleted using the following API request. Replace the uuid in the API request URL with the unique identifier of the Object Storage you wish to delete.

Request

DELETE /1.3/object-storage/{uuid}

Normal response

HTTP/1.0 204 OK

Note that deleting the storage will permanently delete any data on the device and which cannot be reverted.

S3 API Access details

UpCloud Object Storage is fully S3-compliant meaning any existing S3 client you prefer should be able to connect and access your Object Storage. To do so, you will need to configure your S3 client to be able to authenticate with the storage.

Note that the access details for your Object Storage cannot be obtained after the Object Storage has been created. Make sure to store your access and secret keys safely.

If you’ve lost your access details, you can set new keys using the Modify Object Storage request as shown below.

Request

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

Make note of your Object Storage’s endpoint url, access_key and sercret_key which are needed to be able to connect using an S3 client.

If you don’t already have an S3 client you prefer, have a look at S3cmd. Check out the tutorial on how to use S3cmd command-line tool to manage your Object Storage and get started.

File management clients

MSP360 Explorer provides a user interface allowing to access, move and manage files across your local storage and the cloud storage of your choice. Cloud file management software by MSP360™ is available in two versions: Freeware and PRO which both include clients for Windows and macOS.

CloudBerry Object Storage configuration

Cyberduck is a libre server and cloud storage browser for macOS and Windows with support for S3 compliant object storage in addition FTP, SFTP, Dropbox, Google Drive and more. Cyberduck is funded through donation but the software itself is free to download and use.

Cyberduck Object Storage configuration

Command line tools

S3cmd is a free open-source command-line tool and client for uploading, retrieving and managing data for any cloud storage service providers that use the S3 protocol and works great with UpCloud Object Storage. It is best suited for power users who are familiar with command-line programs but is simple enough for beginners to learn quickly as well. It is also ideal for batch scripts and automated backup to S3, for example, by scheduling using cronjobs.

Check out our guide on S3cmd and get started managing your Object Storage tasks.

MinIO Client provides a modern alternative to UNIX commands like ls, cat, cp, mirror, diff, find etc. It supports filesystems and S3 compatible cloud storage services across the board. In addition to being available for download on Windows, macOS and Linux, MinIO is also available as a docker image.

Janne Ruostemaa

  1. Hi! I’d like to know if is there any integration with Node. Thanks !

    Reply
  2. Is there a SDK for Java (like Amazon) or only HTTP calls are allowed?

    Reply
  3. Is there a .Net and .net core client library

    Reply
  4. Does Upcloud support AWS’ getSignedUrl so I can use that to upload/download files directly to my Object Storage?

    Reply
  5. Are you telling me that a simple GET /1.3/object-storage/{uuid}

    Will return to you :
    The “url”, the “access_key”, and the secret key: “secret_key”.
    How’s that secure ?

    Beside why you do not talk about downloading/retrieving the content. Isn’t that the most important? And the one operation that you need to secure the most in a first place.
    And you don’t even mention it.

    Reply
  6. support FTP to object storage?
    Thank you

    Reply

Leave a Reply

Your email address will not be published.

Back to top