Cloud Storage API

Cloud Storage gives developers the ability to integrate with third party apps and sites. One way to do this is by using REST API. 
REST API is a programming interface for interacting with cloud storage. It can be used to perform the following operations:

  • Retrieving information on the current account and separate containers
  • Creating and deleting containers
  • Uploading and deleting files
  • Moving files from one container to another
  • Setting metadata for containers
  • And more

The API is controlled using standard HTTP requests.

What Is REST API

REST API defines a set of functions for which requests can be made and responses can be received. Information is sent over HTTP, which means the API can be used with practically any programming language. Cloud Storage supports OpenStack Swift API and thus can use corresponding libraries for different programming languages.

How to Use the API

All API calls are HTTP requests to the user’s storage URL ({+}http://xxxxx.selcdn.ru+) which contain a certain set of parameters. Calls to the API can be made using any method described in this documentation by writing a request as per the method’s description and executing it. Responses received from requests are also described in this documentation.

This documentation also describes typical errors that may occur while executing requests.

REST API Functions

Authentication

 

Request

URI

Description

GET

{+}https://api.selcdn.ru/auth/v1.0+

Returns the authentication key (token) for accessing storage via API which must to be included in all subsequent requests.

 

Request parameters

 

Parameter

Value

X-Auth-User

account number

X-Auth-Key

storage password

 

Example request:

$ curl -i https://auth.selcdn.ru/ -H "X-Auth-User:xxxx" -H "X-Auth-Key:$password"


Example response:

HTTP/1.1 204 No Content
Date: Tue, 28 Oct 2014 08:55:11 GMT
Server: Selectel_Storage/1.0
X-Expire-Auth-Token: 75846
X-Storage-Url: https://77218.selcdn.ru/
X-Storage-Token: 308243f356f0153c085470d0c855df20
X-Auth-Token: 308243f356f0153c085470d0c855df20
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Expire-Auth-Token, X-Storage-Url, X-Storage-Token, X-Auth-Token


Response parameters

 

Parameters

Value

X-Expire-Auth-Token

period before authorization key expires (sec.)

X-Storage-URL

URL for accessing storage

X-Auth-Token

authorization key

X-Storage-Token

authorization key (matches previous parameter).


Possible errors

 

Code

Description

403

authorization failed

Cloud Storage also supports protocol v2.0 and v3 authentication.

 

Example request for v2.0 authentication

$ curl -i -X POST {+}https://api.selcdn.ru/v2.0/tokens+ -H 'Content-type: application/json' -d '{"auth": {"passwordCredentials": {"username": "22302", "password": "5JFH6Jk1"}}}'
HTTP/1.1 200 OK
Content-Length: 423
Content-Type: application/json
Date: Thu, 19 May 2016 07:17:08 GMT

{"access":{"token":{"id":"49a049462d6943d55b2ccc85abd5fdae","expires":"2016-05-20T13:12:45\n","tenant":{"id":"22302","name":"22302"}},"user":{"id":"22302","name":"22302","roles":[]},"serviceCatalog":[{"endpoints":[{"region":"common","adminURL":"https://api.selcdn.ru/v1/SEL_22302","internalURL":"https://api.selcdn.ru/v1/SEL_22302","publicURL":"https://api.selcdn.ru/v1/SEL_22302"}],"type":"object-store","name":"swift"}]}}


Example request for v3 authentication

$ curl -i {+}https://api.selcdn.ru/v3/auth/tokens+ -XPOST -d '{"auth": { "identity": { "methods": ["password"], "password": { "user": { "id": "43371", "password": "QyjaoXLh"}}}}}'
HTTP/1.1 200 OK
Content-Length: 807
Content-Type: application/json
X-Subject-Token: 614ed749fba45aa218d1ba68c7c83411
Date: Fri, 20 May 2016 12:56:36 GMT
{"token":{"expires_at":"2016-05-21T09:27:53.8459900Z","issued_at":"2016-05-20T15:56:36.8459900Z","methods":["password"],"project":{"domain":{}},"Catalog":[{"endpoints":[{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_43371","region":"RegionOne","interface":"public"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_43371","region":"RegionOne","interface":"admin"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_43371","region":"RegionOne","interface":"internal"}],"type":"object-store","name":"swift","id":""}],"user":{"id":"614ed749fba45aa218d1ba68c7c83411","name":"43371","domain":{"id":"default","name":"Default","links":{}}},"audit_ids":[""]}}

As you can see from this example, the token is sent in the X-Auth-Token response header.

Temporary Tokens

Cloud Storage supports temporary tokens, which users can use to get access to strictly assigned containers. These tokens expire and may last anywhere from for a few minutes to a few hours. When these tokens expire they are no longer valid and users lose container access and cannot perform any API operations.

 

Request

URI

Description

GET

{+}https://api.selcdn.ru/v1/temptokens+

Returns a temporary token for accessing the container defined in the request.


Request parameters

 

Parameter

Value

X-Auth-Token

main user authentication key

X-Container

the container to create a temporary token for

X-ExpireAfter

expiration period for the temporary token in seconds

 

Example request

$ curl -i {+}https://api.selcdn.ru/v1/temptokens+ -H "X-Auth-Token: $token" -H "X-Container: container_name" -H "X-ExpireAfter: $term"

If the request is successfully run, a 204 No Content code is returned. The temporary token will be returned in the X-Auth-Token header.


Example response

HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Auth-Token: bd1bcd683fc0dfa050fa0ab2185445te
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 6000
X-Storage-Token:  bd1bcd683fc0dfa050fa0ab2185445te
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_+...
Date: Fri, 20 May 2016 13:43:39 GMT

Retrieving Account Information 

 

Request

URI

Description

HEAD

{storage_url}

Returns general information about account: total number of containers, total number of objects, total volume of data stored, total volume of data downloaded.


Request parameters

 

Parameters

Value

X-Auth-Token

authorization key


Example request

$ curl -I {storage_url} -H "X-Auth-Token:$token"


Example response

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: c5zzs2wa
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: text/plain; charset=utf-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Account-Object-Count, X-Timestamp, X-Account-Meta-Temp-Url-Key, X-Account-Bytes-Used, X-Account-Container-Count


Response parameters

 

Parameters

Value

X-Account-Bytes-Used

total volume of data saved, in bytes

X-Account-Container-Count

number of containers

X-Account-Object-Count

total number of objects saved

Storage Functions

Retrieving Container Lists

 

Request

URI

Description

GET

{storage_url}

Returns the list of available containers


Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Response parameters

 

Parameters

Value

X-Account-Container-Count

total number of containers in storage space

X-Account-Object-Count

total number of objects in containers

X-Transferred-Bytes

total amount of data downloaded from storage in bytes

X-Received-Bytes

total amount of data downloaded from storage in bytes

 

Example request

$ curl -i -X GET '{storage_url}?format=json' -H "X-Auth-Token:$token"


Example response

HTTP/1.1 200 OK
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: c53zs23аa
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
Content-Length: 300
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Account-Object-Count, X-Timestamp, X-Account-Meta-Temp-Url-Key, X-Account-Bytes-Used, X-Account-Container-Count

[{"count": 1, "name": "test2", "rx_bytes": 363, "tx_bytes": 1006, "type": "public", "bytes": 363}, {"count": 1, "name": "upload", "rx_bytes": 0, "tx_bytes": 0, "type": "private", "bytes": 363}, {"count": 4, "name": "yellow", "rx_bytes": 484666, "tx_bytes": 264846, "type": "public", "bytes": 483748}]

One request can retrieve information on 10,000 containers; if information on more containers is required, additional requests can be made using the marker parameter.

Creating a New Container

 

Request

URI

Description

PUT

{storage_url}/{container_name}

Creates a new container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Type

container type: public or private

X-Container-Meta-Some

container metadata


Example request

$ curl -i -XPUT {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Type: public"


Example response

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: 
Expires: 0
Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate

Retrieving Container Information

 

Request

URI

Description

HEAD

{storage_url}/{container_name}

Returns container information

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key


Example request

$ curl -I {storage_url}/{container_name} -H "X-Auth-Token: $token"


Example response

HTTP/1.1 200 OK
Content-Length: 113
X-Backend-Timestamp: 1445521364.51371
X-Container-Object-Count: 8
Accept-Ranges: bytes
X-Backend-Put-Timestamp: 1445521637.35495
X-Storage-Policy: Policy-0
X-Container-Bytes-Used: 2455570
X-Backend-Delete-Timestamp: 0000000000.00000
X-Container-Meta-Type: gallery
X-Timestamp: 1445521364.51371
X-Backend-Storage-Policy-Index: 0
Content-Type: text/plain; charset=utf-8
X-Backend-Status-Changed-At: 1445521364.56786
X-Container-Domains:
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, X-Container-Object-Count, X-Backend-Put-Timestamp, X-Storage-Policy, X-Container-Bytes-Used, X-Backend-Delete-Timestamp, X-Container-Meta-Type, X-Timestamp, X-Backend-Storage-Policy-Index, X-Backend-Status-Changed-At, X-Container-Domains


Response parameters

 

Parameters

Value

X-Container-Object-Count

number of objects in container

X-Container-Bytes-Used

total volume of all saved objects, in bytes

X-Container-Meta-Type

container type (public or private)

X-Container-Meta-Some

container metadata

X-Container-Domains

domains bound to container

X-Transferred-Bytes

total amount of data downloaded from container in bytes

X-Received-Bytes

total amount of data uploaded to container in bytes

Changing Container Metadata

 

Request

URI

Description

POST

{storage_url}/{container}

Changes a container’s metadata

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Type

container type: public or private

X-Container-Meta-Some

container metadata

 

Example request

curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token"  -H "X-Container-Meta-Type: private" -H "X-Container-Meta-Some: any text"


Example response

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

If any metadata needs to be deleted, it can be given as a value in the X-Remove-Container-Meta-Some header:


Example request

curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token"  -H "X-Container-Meta-Type: private" -H "X-Remove-Container-Meta-Some: any text"


Error codes

 

Code

URI

Description

404

{storage_url}/{container_name}

The requested container does not exist

Deleting a Container

Please note that only empty containers can be deleted.  If the given container contains even one file, the operation will not be executed.

 

Request

URI

Description

DELETE

{storage_url}/{container_name}

Deletes the container given in the request

 

Example request

$ curl -i {storage_url}/new/ -X DELETE -H "X-Auth-Token:$token"


Example response

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:


Error codes

 

Code

Description

404

The requested container does not exist

409

The container contains files

 

Creating a Photo Gallery

 

Request

URI

Description

PUT

{storage_url}/{container}

Activates the function to view images in a gallery for the specified container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Type

container type: public or private

 

Example request

curl -i -XPUT {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Type: gallery"


Example response

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Retrieving a Container File List 

 

Request

URI

Description

GET

{storage_url}/{container_name}

Returns a list of files stored in the given container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Requests may contain the following additional parameters:

  • limit - the maximum number of objects on a list (default - 10 000)

  • marker - objects whose value exceeds the given marker (useful for page navigation and for large numbers of files)

  • prefix - prints objects whose names start with the given prefix in line format

  • path - returns objects in the given folder (virtual folder)

  • delimiter - returns objects up to the given delimiter in the filename

  • format - the format results are returned in (json or xml)

Example request

curl -i {storage_url}/{container_name}/?format=json  -H "X-Auth-Token: $toKen"


Example response

HTTP/1.1 200 OK
X-Container-Object-Count: 3
Accept-Ranges: bytes
X-Container-Meta-Type: gallery
X-Timestamp: 1395042799.81374
X-Container-Bytes-Used: 925740
Content-Type: application/json; charset=utf-8
X-Container-Domains:
Content-Length: 559
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Container-Object-Count, X-Container-Meta-Type, X-Timestamp, X-Container-Bytes-Used, X-Container-Domains

Downloading Containers and Folders as a Zip Archive

It is possible to download the contents of a container or folder as a single zip archive. The option only works for public containers and containers configured as photo galleries.

To download the contents of a container as a zip archive, you need to add the relevant link to the download-all-as-zip=[archive name] query parameter; for example:

$ wget 'https://xxx.selcdn.ru/public_container/?download-all-as-zip=arch.zip'

Unauthorized users can download files as a zip archive (unless the file or gallery download is password protected).

Please note that archived files are not compressed: this function was designed to simplify downloads and not to reduce traffic. The archive will only include the first 10,000 files from a container or folder. All other files will not be added.

Managing Files

Downloading Files from Containers

 

Request

URI

Description

GET

{storage_url}/{container}/{file}

Downloads the given file to the local machine

 

Example request

curl -O {storage_url}/images/image1.png

The X-Auth-Token header is only required for private containers; it is optional for public containers.

The request may also include standard HTTP headers as described in RFC2616:

  • If-Match

  • If-None-Match

  • If-Modified-Since

  • If-Unmodified-Since

Uploading Files to Containers

 

Request

URI

Description

PUT

{storage_url}/{container}/{file}

Uploads a file to the given container


Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Delete-At

time when file will be deleted (in Unix Timestamp format)

X-Delete-After

time (in seconds) before a file is deleted

Etag

MD5 hash of uploaded file

X-Object-Meta-*

metadata of uploaded object

 

Example request

$ curl -i -XPUT {storage_url}/new_container/new_object \    -H "X-Auth-Token: $ \    -H "X-Delete-After: 100" \    -T "./example.gz"


Example response

> HTTP/1.1 100 Continue > HTTP/1.1 201 Created > etag: 0f343b0931126a20f133d67c2b018a3b > Last-Modified: Wed, 29 Oct 2014 12:24:37 GMT

Setting File Expirations

Expiration dates can be set as the default for files uploaded to a container. The time period should be saved in the container’s metadata:

$ curl -i -XPOST {storage_url}/{container_name} \        -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \        -H "X-Container-Meta-Default-Delete-After: 1209600"

In this example, we indicate that all files uploaded to the container are to be saved for 1209600 seconds, i.e. 14 days. Files that expire will be automatically deleted.

Extracting Archives

Archives in .tar, .tar.gz, gzip format can be automatically extracted after being uploaded to storage. This can be done by sending a PUT request with an additional extract-archive query parameter to the container address.


Request parameters

 

Request

URI

Description

PUT

{storage_url}/{container_name}?extract-archive={archive_type}

Extracts the archive in the request.  The archive type is given in the extract-archive parameter (tar, tar.gz or tar.bz2)

 

Example request

curl -i -X PUT {storage_url}/{container_name}/?extract-archive=tar.bz2'        -H "X-Auth-Token: $toKen" -T "photos.tar.bz2"


Example response

{"Response Status": "201 Created", "Response Body": "", "Errors": [], "Number Files Created": 1237}



Parameters

Value

Response Status

response status

Response Body

response body

Errors

error codes

Number Files Created

number of files extracted from archive

Setting Metadata

Request parameters

 

Parameters

Value

X-Object-Meta

metadata that needs to be set or changed

 

Example request

$ curl -i -XPOST {storage_url}/new_container/new_object  -H 
"X-Auth-Token: "$token"  -H "X-Object-Meta-Some: another"

Copying Files in Storage

Cloud Storage can copy files from one folder to another. There are two ways this can be done.

Method 1

 

Request

URI

Description

PUT

{storage_url}/{new_location}

Copies a file to the given folder; the present folder is given in the X-Copy-From header

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Copy-From

path of file that needs to be copied


Example request

$ сurl -i -X PUT {storage_url}/{container_name}/first_copy -H "X-Auth-Token:$token" -H "X-Copy-From: /{container_name/new_object"


Method 2

 

Request

URI

Description

COPY

{storage_url}/{container}/{file}

Copies the given file to the folder given in the Destination header

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

Destination

new filename and path

 

Example request

$ curl -i -X COPY {storage_url}/{container_name}/{file} \    -H "X-Auth-Token: $token" \    -H "Destination: /new_container/second_copy"


Example response

HTTP/1.1 201 Created etag: 0f343b0931126a20f133d67c2b018a3b X-Copied-From: new_container/new_object X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT Last-Modified: Tue, 28 May 2013 06:30:51 GMT

Deleting Files

 

Request

URI

Description

DELETE

{storage_url}/{container_name}/{file}

Deletes the given file

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Example request

$ curl -i -X DELETE {storage_url}/{container_name}/{file} -H "X-Auth-Token: $toKeN"


Example response

HTTP/1.1 204 No Content

Creating Symbolic Links to Files

 When using Cloud Storage as a backend for public services, it often becomes necessary to delineate file access; for example, making files in a private container that are accessible to a wide number of users. For these particular situations, it is possible to create symbolic links. These links can be password protected or have expirations.

 

Request

URI

Description

PUT

{storage_url}/{container}/{link}

Creates a symbolic link to the given file

 

Request parameters

 

Parameters

Value

Content-Type

x-storage/symlink - standard link

x-storage/onetime-symlink - one-time link

x-storage/symlink+secure - standard link password protected

x-storage/onetime-symlink+secure - one-time link, password protected

X-Object-Meta-Location

link destination (relative quoted path to object in storage; for example /container/path/to%20file).

Content-Length

0

X-Object-Meta-Delete-At

time when link will be deleted (in Unix Timestamp format)

X-Object-Meta-Link-Key

hash password (for password protecting links)

Content-Disposition

Indicates how files should be treated: opened in a browser (inline) or downloaded to the local machine (attachment)

 

Example request

curl -i -XPUT {storage_url}/{container_name}/{link}  -H "X-Auth-Token: $token" -H "Content-Type: x-storage/symlink" -H "X-Object-Meta-Location: /{container_name}/{file}"  -H "X-Object-Meta-Link-Key: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c" -H "Content-Length: 0"


Example response

HTTP/1.1 201 Created etag: d41d8cd98f00b204e9800998ecf8427e Last-Modified: Mon, 27 May 2013 13:34:34 GMT

Using this function, special links can be created from which third party users can download files from storage (including from private containers).

Before generating these links, a secret key must first be set. The key can be set on the user level or on the container level. The secret key, which is assigned for the account, lets you create links to all of the files in all of the containers. To set this kind of global key, you must execute an authorized POST request with a X-Account-Meta-Temp-URL-Key header. If links have to be created for only one container, you should send a POST request with X-Container-Meta-Temp-URL-Key header to the container address. Here we should say that the request to set the user key must be executed by the main user; general users do not have the right to change global account settings. An example of a request to set the secret account key:

$ curl -i -XPOST {storage_url} -H "X-Auth-Token: $token" -H "X-Account-Meta-Temp-URL-Key: $key"

Only users who know the key will be able to access the files from this link. The list of IP address the link will be accessible from can be sent using the X-Account-Meta-Temp-URL-Ips and X-Container-Meta-Temp-URL-Ips headers. The addresses must be separated by commas with no spaces between addresses:

$ curl -i -XPOST {+}https://xxx.selcdn.ru/container1+ -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"  -H "X-Container-Meta-Temp-URL-Ips: x.x.x.x,y.y.y.y"


Example in Python

import hmac from hashlib import sha1 from time import time # data for generating links method = "GET"  # access method expires = int(time()) + 60  # link lifetime (60 seconds) path = "/container/dir/file"  # full path to file in storage
link_secret_key = "secret_word"  # secret key # generating access key hmac_body = '%s\n%s\n%s' % (method, expires, path) sig = hmac.new(link_secret_key, hmac_body, sha1).hexdigest()  # access key
print expires, sig

The key from the result is indicated in the link:

{storage_url}/container/dir/file?temp_url_sig=$sig&temp_url_expires=$expires

where:

  • {storage_url}  is the base domain

  • temp_url_sig is the access key

  • temp_url_expires is the link’s expiration time (unixtime).

If a domain is bound to a container, then it can be given in the link.  In such cases, the container name does not need to be given:

{+}https://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227+

Content-Disposition management is supported for distributing data over a link. To do this, the filename parameter must be added with the appropriate value:

{storage_url}/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc

The secret key can be changed; afterwards, previously generated links will be invalid.

 Links can be created for uploading files to storage. With these links, third party users, even those without storage accounts, can upload files to containers and folders. This function can be useful for a variety of purposes: for organizing file transfers, for uploading user content to sites, for quickly saving backups, etc.

Upload links are created by sending a PUT request to the address {storage_url}/{container_name}/upload.

 

Request

URI

Description

PUT

{storage_url}/{container}/upload

Creates a link from which third party users can upload files to the given container

 

Request parameters

 

Parameters

Value

Content-Type

types of links:

  • x-storage/sendmefile+inplace - uploads only one file with the given filename (the name of the link is the filename the uploaded file will be saved as);

  • x-storage/sendmefile+timepostfix - uploads files and adds a timestamp to the filename with the upload time (accounting for file extension);

  • x-storage/sendmefile+autopostfix - uploads files and adds a unique identifier to the filename (accounts for the file extension);

  • x-storage/sendmefile+folderday - uploads files to a folder whose name is the upload date (year and day);

  • x-storage/sendmefile+folderhour - uploads files to a folder whose name is the upload date and time (day and hour);

  • x-storage/sendmefile+folderuniq - uploads files to a folder with a uniquely generated name

X-Object-Meta-Sendmefile-Disable-Web 

yes/no

Enables/disables the web interface when uploading files. The web interface is enabled by default

X-Object-Meta-Sendmefile-Max-Size

maximum file size for uploads, in bytes

X-Object-Meta-Sendmefile-Allow-Overwrite

yes/no

Allows files to be rewritten if already in storage (rewrites are prohibited by default)

X-Object-Meta-Sendmefile-Ignore-Filename

yes/no

Renames uploaded file according to given parameters

X-Object-Meta-Sendmefile-Secret

SHA-1 hash password (for links that are password protected)

X-Filename

name the uploaded file will be saved as in storage

X-Sendmefile-Session-Id 

upload session identifier

 

Example request

$ curl -i -XPUT {storage_url}/container/upload  -H "X-Auth-Token: $token"    -H "Content-Type: x-storage/sendmefile"     -H "X-Object-Meta-Sendmefile-Max-Size: 52428800"  -H "X-Object-Meta-Sendmefile-Expire: 14400"    -H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8" -d "Text on the upload page"


Response parameters

 

Parameters

Value

X-Uploaded-As

Filename the uploaded file will be saved as in storage

Automatically Extracting Archives in Background Mode

Archives in tar, tar.gz, and gzip format can be automatically extracted in background mode after being uploaded to Cloud Storage. This is done by sending a PUT request with the additional query parameter extract-archive-v2 to the container address.

Request parameter

 

Request

URI

Description

PUT

{storage_url}/{container_name}?extract-archive-v2={archive_type}

Unloads archives sent in the request body in the given container


Example request

curl -i -X PUT {storage_url}/{container_name}/?extract-archive-v2=tar.bz2' -H "X-Auth-Token: $toKen" -T "photos.tar.bz2"


Example Response

HTTP/1.1 100 Continue
 
HTTP/1.1 201 Created
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 0
Content-Type: text/html
Etag: a1adb438cb26e91228870158a2062ef2
Extract-Id: 6a62579d-9ee2-2a32-26a4-207d5a47af2a


Retrieving Status on Background Extractions

Request

URI

Description

GET

{storage_url}/v1/extract-archive/{extract-id}

 

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Example request

$ curl -i {+}https://api.selcdn.ru/v1/extract-archive/+6a62579d-9ee2-2a32-26a4-207d5a47af2a -H "X-Auth-Token: 49a049462d6943d55b2ccc85abd5fdae"
 
HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Auth-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 60
X-Storage-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_43371+
Date: Fri, 20 May 2016 13:02:00 GMT

Managing HTTP File Headers

HTTP headers can be set for hosting files in Cloud Storage via API. Using headers, data is cached on the client side and on intermediate proxy servers. Parameters can also be given for processing cross-origin requests (CORS). The following headers are supported:

  • Cache-Control

  • Expires

  • Origin

  • Access-Control-Allow-Origin

  • Access-Control-Max-Age

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Credentials

  • Access-Control-Expose-Headers

  • Access-Control-Request-Headers

  • Access-Control-Request-Method

  • Content-Disposition (only for end files)

  • Strict-Transport-Security (only at container level)

Headers are set on the container level. Header values are set as metadata:

$ curl -i -XPOST {+}https://xxx.selcdn.ru/new_container+ \    -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \    -H "X-Container-Meta-Access-Control-Request-Method: HEAD, GET" \    -H "X-Container-Meta-Cache-Control: public" \    -H "X-Container-Meta-Strict-Transport-Security: max-age=31536000; includeSubDomains"

Values for other headers are similarly set.

Special Pages

Cloud Storage is often used as a platform for storing static sites. The API includes some functions for this situation. One of these is the ability to set up special pages. Special pages include:

  • index page - a file in a container that is returned for anonymous GET requests to that container or folder;

  • error (404) file - a file returned for anonymous GET requests to a nonexistent object;

  • a list of files and folders in a container that is returned for anonymous GET requests to that container.

 

Index Page

Request

URI

Description

PUT

{storage_url}/{container}{index_file}

Assigns the index page for the given container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Web-Index

path to desired index file

 

Requests may give an absolute or relative path to the file:

 

Web Index

Request

Returned file

/index.html

GET /container/

GET /container/dir1/

/container/index.html

index.html

GET /container/

/container/index.html

 

GET /container/dir1/dir2/

/container/dir1/dir2/index.html

or (if no file is present)

/container/index.html

 

Example request

$ echo "<html>custom_index_file</html>" > my_index.html # upload to storage $ curl -i -X PUT {storage_url}/{container_name}/my_index.html \    -H "X-Auth-Token: $token" \    -T "./my_index.html" > HTTP/1.1 100 Continue > HTTP/1.1 201 Created > etag: b302ffc3b75770453e96c1348e30eb93 > Last-Modified: Mon, 27 May 2013 14:42:04 GMT

There are other ways to assign index pages; we assign a Web Index value for the container: 

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \    -H "X-Container-Meta-Web-Index: /my_index.html" > HTTP/1.1 204 No Content # for anonymous requests, we get the contents of the given file
$ curl -i {storage_url}/new_container/ > HTTP/1.1 200 OK > last-modified: Mon, 27 May 2013 14:27:57 GMT > etag: b302ffc3b75770453e96c1348e30eb93 > accept-ranges: bytes > Content-Length: 31 > Content-Type: text/html > access-control-request-method: HEAD, GET > > <html>custom_index_file</html>

404 Error

 

Request

URI

Description

PUT

{storage_url}/{container_name}/{error_file}

Configures the error file for the given container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Web-404-Page

path to error file

 

The value for the header X-Container-Meta-Web-404-Redirect can be a file in the container or external link.

Examples:

 

Web-404-Redirect

Request

Forwarding address

/404.html

GET /container/nofile

GET /container/dir1/nofile

/container/404.html

404.html

GET /container/nofile

/container/404.html

 

GET /container/dir1/dir2/nofile

/container/dir1/dir2/404.html

or (if no file is present)

/container/dir1/404.html

or

/container/404.html

{+}http://test.test+

GET /container/nofile

GET /container/dir1/nofile

{+}http://test.test+

 

To transfer information about the initially requested file, special template parameters may be used:

  • {container} - container name

  • {path} - path to file relative to the container

Example request

$ curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}" > HTTP/1.1 204 No Content #

If an anonymous request is sent for a nonexistent object, we get redirected to the given file:

$ curl -i {storage_url}/{container_name}/non_existing_object > HTTP/1.1 307 Temporary Redirect > Location: {+}http://xxx.selcdn.ru/404.html?file=non_existing_object+

By default, error pages are returned for a 404 code. Other response codes can also be given: 200 and 307:

$ curl -i -XPOST {storage_url}/new_container -H "X-Auth-Token: $token" -H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}?{code}"

Replace {code} with the necessary error code.

File Listings

 

Request

URI

Description

POST

{storage_url}/{container}

Enables file listing for the container in the request

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Web-Listings

on/off - enables or disables listing for containers

X-Container-Meta-Web-Listings-CSS

link to style file, used for HTML format (optional)

X-Container-Meta-Web-Listings-Sort

Sorting options for listings. Possible values:

name_asc

name_desc

date_asc

date_desc

size_asc

size_desc

 

Example request

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: $token" \    -H "X-Container-Meta-Web-Listings: on" > HTTP/1.1 204 No Content #

To retrieve a file listing from an anonymous request:

$ curl -i {storage_url}/{container_name}/ \    -H "X-Web-Mode: listing"


Example response

HTTP/1.1 200 OK > Content-Type: application/json; charset=UTF-8 > X-Container-Object-Count: 4 > > <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "{+}http://www.w3.org/TR/html4/loose.dtd+"> > <html> > ... > </html>

Responses can be returned in HTML format by using the X-Container-Meta-Web-Listings-CSS header. This header’s value should refer to the style file in the container or be a link to an external style file.

Example

 

Web-Listings-CSS

Description

my.css or /my.css

a style file in the given container will be used

{+}http://my_site/my.css+

a style file from an external site will be used

 

To set the Web-Listings-CSS value for a container:

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: $token" \    -H "X-Container-Meta-Web-Listings-Css: /my_style.css" > HTTP/1.1 204 No Content

Setting Limits

Cloud Storage lets you limit the amount of data stored in individual containers and by specific accounts.

 For Containers

 To set a limit for containers, a POST request must be sent to the container address with the maximum number of objects or amount of data (in bytes) in the header.

 

Request

URI

Description

POST

{storage_url}/{container}

Sets limits which are entered as values for the X-Container-Meta-Quota-Bytes and X-Container-Meta-Quota-Count headers.

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Meta-Quota-Bytes

maximum storage space in the container, in bytes

X-Container-Meta-Quota-Count

maximum number of files and folders in the container

 

Example request

$ curl -i -XPOST {storage_url}/{container_name}  -H "X-Auth-Token: $token"   -H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

For Accounts

 

Request

URI

Description

POST

{storage_url}

Sets limits which are entered as values for the headers X-Container-Meta-Quota-Bytes and X-Container-Meta-Quota-Count.

 

Example request

$ curl -i -XPOST {storage_url}/{container_name}  -H "X-Auth-Token: $token"   -H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

Versioning

Electronic documents usually undergo many changes. Often not only the latest version of the document needs to be saved, but several previous versions as well. To facilitate this, Cloud Storage supports version.

 

Request

URI

Description

PUT

{storage_url}/{container}/

Enables versioning for the given container.  Versions will be saved in the container whose name is set in the X-Version-Location header. Containers for saving these versions should be created ahead of time.

 

Request parameters

 

Parameters

Description

X-Auth-Token

authorization key

X-Version-Location

name of container where versions will be saved

 

Example request

$ curl -i -X PUT -H "X-Auth-Token: $token" -H "X-Versions-Location: $container" {storage_url}/{container_name}

Example response

HTTP/1.1 202 Accepted Content-Length: 76 Content-Type: text/html; charset=UTF-8 Access-Control-Allow-Origin: * Access-Control-Expose-Headers: Expires: 0 Pragma: no-cache Cache-Control: no-cache, no-store, must-revalidate

Versioning can be disabled by sending a POST request with the header X-Remove-Versions-Location to the container address. The contents of this header are optional.

 

Request

URI

Description

POST

{storage_url}/{container}/

Disables versioning for the given container.

 

Request parameters

 

Parameters

Description

X-Auth-Token

authorization key

X-Remove-Versions-Location

may include optional values

 

Example request

$ curl -i -X PUT -H "X-Auth-Token: $token" -H "X-Remove-Versions-Location: x" {storage_url}/{container_name}

Large Object Support

The maximum file upload size is 20 GB. However, by using segmenting you can upload files regardless of their size.

There are two techniques for uploading large objects: dynamic and static.

A dynamic upload breaks the object into segments, and then creates a manifest. This is an empty file in the X-Object-Manifest header, which contains an identifier for the container that all of the segments were uploaded to.

Segments should be uploaded before creating and updating the manifest: the object in this case will not be available for download until all of the segments have been uploaded.

Example

To upload segments:

curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000001 --data-binary '1' curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000002 --data-binary '2' curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000003 --data-binary '3' #

To create the manifest:

curl -X PUT -H 'X-Auth-Token: $token' \    -H 'X-Object-Manifest: container/myobject/' \    {storage_url}/{container_name}/{object_name} --data-binary '' #

To download all of the segments as a single object:

curl -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}

For a static upload, a static manifest has to be created that gives the path to the segments, their checksum (Etag) and size. This manifest is saved in a special file.

Example manifest

[{"path": "/cont/object",  "etag": "etagoftheobjectsegment",  "size_bytes": 10485760,  }, ...]

To upload the manifest file, a PUT request with the query parameter ?multipart-manifest=put and X-Static-Large-Object: True header has to be sent.

To retrieve the manifest file, a GET request with the query parameter ?multipart-manifest=get has to be executed.

All of the segments and manifest file can be deleted by sending a DELETE request with the query parameter ?multipart-manifest=delete.

Managing Users

Cloud Storage lets you flexibly manage access rights to containers. This may be useful when Cloud Storage needs to interact with third party applications or organize secure file transfers between multiple users.

By default, after registering for Cloud Storage, you will have the status as the primary user and have access to all containers and folders. You can also create additional users, which will have access only to strictly defined objects. This can be done from the graphic control panel or API. API instructions are described below.

Viewing User List

 

Request

URI

Description

GET

{storage_url}/v1/users/

Returns a list of users in json format

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Response parameters

 

Parameters

Value

name

user name

activate

active user identifier (true or false)

acl_containers_w

list of containers user has write access to

acl_containers_r

list of containers user has read access to

password_plain

user password

 

Example request

$ curl -i {+}https://api.selcdn.ru/v1/users?format=json+  -H "X-Auth-Token: $token"


Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 580
[{"active": true, "acl_containers_w": [], "password_plain": "5216Kr1", "name": "user1", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2"], "password_plain": "OPEa222oR5", "name": "user2", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2", "container1", "container4", "container5"], "password_plain": "GIoIRFBKe", "name": "user3", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2", "container3"], "password_plain": "poIT5fae", "name": "user6", "acl_containers_r": ["container2"]}]

Creating New Users

 

Request

URI

Description

PUT

{storage_url}/v1/users/{user_name}

Creates a user with the given name

 

Request parameters

 

Parameters

Value

X-Auth-Key

password for new user

X-User-Active

active user identifier (true or false)

X-User-ACL-Container-R

list of containers new user will have read access to

X-User-ACL-Container-W

list of containers new user will have write access to

X-User-Store-Password

indicates if the new user’s password has to be saved in an open base (equivalent of “Save password on Selectel servers” in the control panel). To save the password in the base, the value yes must be transferred in the header

 

Example request

curl -i -XPUT {storage_url}/users/{username} -H "X-Auth-Token: $token" -H "X-Auth-Key: 123456" -H "X-User-ACL-Containers-W: container1, container2, container3" -H "X-User-ACL-Containers-R: container4" -H "X-User-Store-Password: yes" -H "X-User-Active: on"


Example response

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 0

 

Changing Primary User's Password

Request

URI

Description

PUT

{storage_url}/v1/users

Changes the primary user’s password

 


Request parameters

 

Parameters

Value

X-Auth-Key

user password

X-User-Store-Password

indicates if the user’s password has to be saved in an open base (equivalent of “Save password on Selectel servers” in the control panel). To save the password in the base, the value yes must be transferred in the header

 

Example request

curl -i -XPOST {storage_url}/v1/users -H "X-Auth-Token: $token" -H "X-Auth-Key: 123456" -H "X-User-Store-Password: yes"

Deleting Users

 

Request

URI

Description

POST

{storage_url}/users/{user_name}

Deletes the given user

 

Example request

$ curl -i -XDELETE {+}https://selcdn.ru/users/1+ -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"

Manging Domains

Cloud Storage lets you bind domains to containers. All operations pertaining to domains can be performed from the API.

 Retreiving Domain Lists

 

Request

URI

Description

GET

{storage_url}/domains

Returns a list of all domains bound to containers in the console.

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Example request

curl -i {+}https://api.selcdn.ru/domains+ -H "X-Auth-Token:  $token"


Example response

HTTP/1.1 200 OK
Content-Length: 69
Content-Type: text/html
Date: Mon, 16 May 2016 07:36:35 GMT

Base Domains:
77218.selcdn.ru
77218.selcdn.com
Containers Domains:
container1  domain1.ru
container2  domain1.ru

Binding Domains

 

Request

URI

Description

POST

{storage_url}/{container_name}

Binds the domain given in the request to the container

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Add-Container-Domains

name of domain to bind to container

 

Example request

$ curl -i {storage_url}/{container_name} -XPOST -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

Deleting Domains

 

Request

URI

Description

POST

{storage_url}/{container_name}

Deletes the domain given in the request

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Remove-Container-Domains

name of domain to delete

 

Example request

$ curl -i {storage_url}/{container_name} -XPOST -H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

Changing Bound Domain Lists

 

Request

URI

Description

POST

{storage_url}/{container_name}

Replaces current domain list with list transferred in request

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Container-Domains

list of domains, separated by a space

 

Example request

$ curl -i https://ххххх.selcdn.ru/{container_name} -H "X-Auth-Token:$token" -XPOST -H "X-Сontainer-Domains: domain1.rudomain2.ru"

After executing this command, all domains bound to the container will be replaces with the domains sent in the X-Container-Domains header.

If several domains are bound to a container and they need to be deleted, the value 0 should be sent in the X-Container-Domains header:

$ curl -i https://ххххх.selcdn.ru/{container_name} -H "X-Auth-Token:$token" -XPOST -H "X-Сontainer-Domains: 0"

Manging User SSL Certificates

Viewing Certificate List

 

Request

URI

Description

GET

{storage_url}/v1/ssl

Returns a list of certificates

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Example request

$ curl -i {+}https://api.selcdn.ru/v1/ssl+ -H "X-Auth-Token:$token" -XGET

Viewing Certificate Information

 

Request

URI

Description

GET

/v1/ssl/{cert_name}

Returns information on certificates

 

Example request

$ curl -i https://api.selcdn.ru/v1/ssl/\{cert_name} -H "X-Auth-Token:$token" -XGET

Adding Certificates

 

Request

URI

Description

PUT

https://api.selcdn.ru/v1/ssl/{cert_name}

Adds a new certificate

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

The certificate name ({cert_name}) needs to be sent as 001_cert1, where the first part (the number) is the user login, and the second part (cert1) a certificate name. Certificate names cannot be duplicated. The certificate and private key are given in the request body as one file.


Example request

$ curl -I {+}https://api.selcdn.ru/v1/ssl/001_cert1+ -H "X-Auth-Token:$token" -XPUT -T ./cert1.pem

Deleting Certificates

 

Request

URI

Description

DELETE

{storage_url}/ssl/{cert_name}

Deletes the given certificate

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

 

Example request
$ curl -I {+}https://api.selcdn.ru/v1/ssl/001_cert1+ -H "X-Auth-Token:$token" -XDELETE

Clearing the CDN Cache

 

Request

URI

Description

PURGE

{storage_url}/cdn

Purges the CDN cache

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

Content-Length

size of request body

 

The request body must contain the full address of the pages (each on a new line) the cache should be cleared for. The size of the response body should be sent in the Content-Length header (see above).

Example request

$ curl -i -X PURGE {+}https://api.selcdn.ru/v1/cdn+ -H "X-Auth-Token: $token" -d $'https://ххххх.selcdn.com/container1/file1'

 

Example response

HTTP/1.1 200 OK
Date: Mon, 16 May 2016 09:45:15 GMT
Content-Length: 268
Content-Type: text/plain; charset=utf-8

{"estimatedSeconds": 5, "progressUri": "/ccu/v2/purges/e4561042-1b4a-11e6-9024-f3cf5304c77a", "purgeId": "e4561042-1b4a-11e6-9024-f3cf5304c77a", "supportId": "17PY1463391915374207-348128448", "httpStatus": 201, "detail": "Request accepted.", "pingAfterSeconds": 300}

Please note that the CDN cache is purged five seconds after the request is executed.

 Retrieving Logs

 

Request

URI

Description

POST

{storage_url}/logs

Creates a container with the name logs and downloads logs to it for the given period

 

Request parameters

 

Parameters

Value

X-Auth-Token

authorization key

X-Start-Time

start of period, Y-m-d H:M:S

X-End-Time

end of period, Y-m-d H:M:S

X-Limit

maximum number of entries to return in the request

 

Example request

$ curl -i -XPOST {+}https://api.selcdn.ru/v1/logs+ -H "X-Auth-Token: 49a049462d6943d55b2ccc85abd5fdae" -H "X-Start-Time: 2016-02-02 09:00:00" -H "X-End-Time: 2016-05-02 12:00:00"

After compilation, the file with logs will be saved in the private container named logs.