Tutorials How to manage UpCloud Object Storage via API

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 all request 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 which the user has permissions for 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": [
      {
        "access_key": "UCOBTAWDLKHGSEOUAWD2",
        "created": "2020-07-23T05:06:35Z",
        "description": "Example object storage",
        "name": "example-object-storage",
        "quota_gb": 500,
        "secret_key": "adNCEblese7HhidwIgRVNxvd+x546VLm0azw7d9e",
        "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": {
     "access_key": "UCOBTAWDLKHGSEOUAWD2",
     "created": "2020-07-23T05:06:35Z",
     "description": "Example object storage",
     "name": "example-object-storage",
     "quota_gb": 500,
     "secret_key": "adNCEblese7HhidwIgRVNxvd+x546VLm0azw7d9e",
     "state": "started",
     "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
     "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 quota_gb 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",
    "quota_gb": 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": {
      "access_key": "JT9WE882AZ548P5F1OZ2",
      "created": "2020-07-23T05:06:35Z",
      "description": "data-object-storage",
      "name": "data-object-storage",
      "quota_gb": 500,
      "secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP",
      "state": "started",
      "url": "https://data-object-storage.nl-ams1.upcloudobjects.com/",
      "used_gb": 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.

Attribute Accepted value Description
description 1-255 characters Short description for the Object Storage
access_key 3-255 characters Access key used to identify user
secret_key 8-255 characters Secret key used to authenticate user
quota_gb 2505001000 Size 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"
  }
}

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

HTTP/1.0 200 OK
{
  "object_storage": {
    "uuid": "example-object-storage",
    "name": "Example object storage",
    "zone": "fi-hel1",
    "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
    "access_key": "JT9WE882AZ548P5F1OZ2",
    "secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP",
    "quota_gb": 500,
    "used_gb": 42,
    "state": "started",
    "created": "2020-07-23T05:06:35Z"
  }
}

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 and 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.

You can find the access details for your Object Storage by using the API request below.

Request

GET /1.3/object-storage/{uuid}

Response

HTTP/1.0 201 OK
{
  "object_storage": {
    "uuid": "063881d4-edc5-4102-8214-9b7e11edb9cb",
    "name": "app-object-storage",
    "description": "app-object-storage",
    "zone": "nl-ams1",
    "url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
    "access_key": "JT9WE882AZ548P5F1OZ2",
    "secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP",
    "quota_gb": 500,
    "used_gb": 0,
    "state": "started",
    "created": "2020-07-23T05:06:35Z"
  }
}

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

DragonDisk is a powerful file manager for all cloud storage solutions that provide compatibility with S3 API. It allows organizing and sharing data using a simple and intuitive interface similar to common file explorers. DragonDisk is free and cross-platform, with clients for Windows, macOS and Linux.

Dragondisk 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 service across the board. In addition to being available for download on Windows, macOS and Linux, MinIO is also available as a docker image.

Editor-in-chief and Technical writer at UpCloud since 2015. Cloud enthusiast writing about server technology and software.

2 thoughts on “How to manage UpCloud Object Storage via API

Leave a Reply

Your email address will not be published. Required fields are marked *

Locations

Helsinki (HQ)

In the capital city of Finland, you will find our headquarters, and our first data centre. This is where we handle most of our development and innovation.

London

London was our second office to open, and a important step in introducing UpCloud to the world. Here our amazing staff can help you with both sales and support, in addition to host tons of interesting meetups.

Singapore

Singapore was our 3rd office to be opened, and enjoys one of most engaged and fastest growing user bases we have ever seen.

Seattle

Seattle is our 4th and latest office to be opened, and our way to reach out across the pond to our many users in the Americas.