Skip to main content

Swift

Using the Swift API (API based on OpenStack Object Storage API), you can work with S3 resources:

  • view information about the number and volume of buckets and objects within an account;
  • create and remove buckets;
  • manage bucket limits;
  • upload, view, copy, move, download, and remove objects in buckets.

To access the Swift API, the user must have a role with access to a project in S3; for more details, see the documentation guide Manage S3 access.

Authorization

Authorization in Swift API is performed using an IAM token for a project, which is passed in every request in the X-Auth-Token. header.

The address (URL) can be viewed in the list of URLs.

Request example for viewing the list of buckets in an account project:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'

Specify:

  • <x_auth_token> — IAM token for a project;
  • <swift_domain> — Swift API domain in the pool where S3 is located;
  • <project_id> — project identifier. You can find the identifier in the Control panel in the S3 section → project menu → Project management. The identifier is listed under the project name.

Storage

HEAD/v1/ {project_id}Get information about the storage
GET/v1/ {project_id}Get information about the storage and a list of buckets
POST/v1/ {project_id}Manage storage metadata

Get information about the storage

Returns metadata with information about the number and storage volume of buckets and objects.

Request example

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'

Response example

On success, the request returns a response with code 204.

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: 00000
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
X-Account-Meta-<...>: anyheader
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6

Response parameters

ParameterValue
X-Account-Bytes-UsedTotal volume of stored data (in bytes)
X-Account-Container-CountNumber of buckets
X-Account-Meta-<...>Metadata, where <...> is a custom header
X-Account-Meta-Temp-Url-KeySecret key used to access objects in a private bucket via a temporary URL (if available)
X-Account-Object-CountTotal number of stored objects
X-Account-Storage-Policy-Policy-0-Bytes-UsedTotal volume of stored data by storage policy, where Policy-0 — policy name
X-Account-Storage-Policy-Policy-0-Container-CountNumber of buckets using a storage policy, where Policy-0 — policy name
X-Account-Storage-Policy-Policy-0-Object-CountNumber of objects using a storage policy, where Policy-0 — policy name
X-Openstack-Request-Id
X-Trans-Id		Request ID
X-TimestampDate and time in UNIX format when the account, bucket, or object was created
DateDate and time the request was sent

Get information about the storage and a list of buckets

Returns information about the storage and a list of buckets.

A single request outputs a list that can contain up to 10,000 buckets. If there are more buckets, use additional requests with the query parameter marker.

To get additional information about buckets (size, update date, etc.), use the query parameter?format=json.

Request example

curl \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'

Response example

bucket1
bucket2
bucket3

Manage storage metadata

Sets, replaces, or deletes metadata passed in the request header.

Request headers

HeaderDescription
X-Account-Meta-<...>Storage metadata to be set, where <...> is a custom header
X-Remove-Account-Meta-<...>Storage metadata required to be deleted, where <...> is a custom header

Request example

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Account-Meta-<...>: anyheader' \
'https://<swift_domain>/v1/<project_id>'

Response example

On success, the request returns a response with code 204.

Buckets

HEAD/v1/ {project_id} /{bucket_name}Get bucket metadata
GET/v1/ {project_id} /{bucket_name}Get a list of objects and bucket metadata
PUT/v1/ {project_id} /{bucket_name}Creating a bucket
POST/v1/ {project_id} /{bucket_name}Manage bucket metadata
DELETE/v1/ {project_id} /{bucket_name}Remove a bucket

Get bucket metadata

Displays bucket metadata, including the number of objects, storage volume (in bytes), and bucket headers.

Request example

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On success, the request returns a response with code 204.

Get a list of objects and bucket metadata

Returns bucket metadata and displays a list of objects.

A single request outputs a list that can contain up to 10,000 objects. If there are more objects, use additional requests with the query parameters marker and limit.

Request example

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On success, the request returns a response with code 200 or 204.

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/plain
X-Container-Bytes-Used: 0
X-Container-Meta-Quota-Bytes: 52428800
X-Container-Meta-Quota-Count: 1000
X-Container-Meta-Type: public
X-Container-Object-Count: 1
X-Container-Storage-Policy-Index: 0
X-Container-Storage-Policy-Name: Policy-0
X-Openstack-Request-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Storage-Policy: Policy-0
X-Timestamp: 1688648194.11923
X-Trans-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Versions-Enabled: true
Date: Thu, 13 Jul 2023 15:13:53 GMT
Content-Length: 120
Object1
Object2
Object3

Response parameters

ParameterValue
X-Container-Object-CountNumber of objects in the bucket
X-Container-Bytes-UsedVolume of objects in the bucket (in bytes)
X-Container-Meta-TypeBucket type
X-Container-Meta-Quota-BytesMaximum storage capacity (in bytes)
X-Container-Meta-Quota-CountMaximum number of objects in the bucket
X-Container-Meta-<...>Bucket metadata, where <...> is a custom header
X-Versions-EnabledWhether bucket versioning is enabled

Create a bucket

Creates a bucket with the parameters specified in the request.

Request headers

HeaderDescription
X-Container-Meta-Typepublic (public);
  • private (private)
  • Bucket type:
X-Container-Meta-<...>Bucket metadata. Specify \\<...> - metadata header
X-Storage-PolicyPolicy-0 (default) — standard storage;
  • cold — cold storage
  • Storage class:
X-Versions-EnabledWhether bucket versioning is enabled
X-Container-Meta-Default-Delete-AfterRetention period for all objects in the bucket (in seconds)

Request example

curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Type: public' \
-H 'X-Container-Meta-<...>: anyheader' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On success, the request returns a response with code 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6

Manage bucket metadata

Sets, replaces, or deletes metadata passed in the request header.

Request headers

HeaderDescription
X-Container-Meta-Typepublic (public);
  • private (private)
  • Bucket type:
X-Container-Meta-<...>Bucket metadata to be set, where <...> is a custom header
X-Remove-Container-Meta-<...>Bucket metadata required to be deleted, where <...> is a custom header
X-Versions-EnabledWhether bucket versioning is enabled

Request example

Changing the bucket type:

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Type: private' \
-H 'X-Versions-Enabled: true' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On success, the request returns a response with code 204.

Remove a bucket

Removes a bucket in the storage. Before removing a bucket, remove all objects in it.

Request example

curl -i -XDELETE \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On success, the request returns a response with code 204.

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: Text/html; charset=UTF-8

Objects

GET/v1/ {project_id} /{bucket_name} /{object_name}Get object
PUT/v1/ {project_id} /{bucket_name} /{object_name}Upload an object
POST/v1/ {project_id}Delete multiple objects
POST/v1/ {project_id} /{bucket_name} /{object_name}Manage HTTP headers and object metadata
COPY/v1/ {project_id} /{bucket_name} /{object_name}Copy an object
DELETE/v1/ {project_id} /{bucket_name} /{object_name}Delete an object

Get object

Displays the body and headers of the object.

Request example

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Response example

On success, the request returns a response with code 200.

Upload an object

Uploads an object to a bucket. Such an upload is used for objects up to 100 MB in size. For larger objects, use segmented upload.

When using the X-Copy-From header, you can upload a copied object to a bucket. The object is copied along with the X-Delete-At header regardless of where the header was set (on the object or bucket).

Request headers

HeaderDescription
X-Delete-AtObject deletion time in Unix Timestamp format
X-Delete-AfterObject retention period (in seconds)
EtagEtag identifier
X-Object-Meta-<...>Object metadata, where <...> is a custom header
X-Copy-FromPath to the object to be copied

Request example

Upload an object:

curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Delete-After: 180' \
-d "@<object_body>" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Specify:

  • <object_body> — object body;
  • <object_name> — the name that will be assigned to the object.

Copy an object:

curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Copy-From: /<bucket_name_1>/<object_name_1>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name_2>/<object_name_2>'

Specify:

  • <bucket_name_2> — the bucket to which the object will be copied;
  • <object_name_2> — the name with which the object will be copied;
  • <bucket_name_1> — the bucket where the object being copied is located;
  • <object_name_1> — the object that needs to be copied.

Response example

When uploading an object, on success, the request returns a response with code 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: b65ad34618e410d9d8bf624d61f8a980
Date: Thu, 15 Mar 2023 07:31:32 GMT

When copying an object, on success, the request returns a response with code 201.

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

Delete multiple objects

Removes multiple objects simultaneously, including objects from different buckets. Objects are removed sequentially.

Request example

Removing objects from different buckets:

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Content-Type: text/plain' \
-d $'<bucket_name_1>/<object_name_1>\n<bucket_name_2>/<object_name_2>' \
'https://<swift_domain>/v1/<project_id>?bulk-delete=true&format=json'

Specify:

  • <bucket_name_1>/<object_name_1> — path to the object in the first bucket;
  • <bucket_name_2>/<object_name_2> — path to the object in the second bucket;
  • \n — line break, must be specified between objects.

Response example

On success, the request returns a response with code 200.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 08 Jun 2018 13:37:53 GMT
Content-Length: 101
{'Number Not Found':0,'Response Status':'200 OK','Response Body':'','Errors':null,'Number Deleted':2}

Manage HTTP headers and object metadata

Sets values for custom and HTTP headers specified in the request. Headers are used to control caching on both the client side and intermediate proxy servers.

Supported HTTP headers:

  • Cache-Control
  • Content-Encoding
  • Content-Type
  • Content-Disposition
  • Link

Request headers

HeaderDescription
X-Container-Meta-<...>Header whose parameters need to be set. Specify <...> — header (e.g., X-Container-Meta-Cache-Control).

Request example

Adding the Link header to an object:

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Link: rel=canonical' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Adding a custom header:

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Object-Meta-Some: metadata' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Response example

A request to add the Link header returns a response with code 202 on success.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

On success, the request to add a custom header returns a response with code 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: d41d8cd98f00b204e9800998ecf8427e

Copy an object

The object will be copied to another bucket or to a different prefix. If the X-Fresh-Metadata header is set to true, then upon copying, a new object will be created with new headers, including ones without X-Delete-At.

Request headers

HeaderDescription
DestinationPath where the object will be copied

Request example

curl -i -XCOPY \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Destination: /<bucket_name_2>/<object_name_2>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name_1>/<object_name_1>'

Specify:

  • <bucket_name_1> — the bucket where the object being copied is located;
  • <object_name_1> — the object that needs to be copied.
  • <bucket_name_2> — the bucket to which the object will be copied;
  • <object_name_2> — the name with which the object will be copied.

Response example

On success, the request returns a response with code 201.

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

Delete an object

The object will be removed from the bucket.

To remove a segmented object, use the query parameter ?multipart-manifest=delete — the object segments and the manifest will be removed.

Request example

curl -i -XDELETE \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Response example

On success, the request returns a response with code 204.

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

Headers for delayed deletion

Headers are specified when sending PUT and POST requests and determine when the object will be automatically deleted from the storage.

HeaderValueDescription
X-Delete-AtTimestamp value in Unix Epoch format (seconds)The server will store the object until the time passed in the header. To convert it into a human-readable format, you can use EpochConverter.
X-Delete-AfterInteger number of secondsThe server converts this value into the X-Delete-At header. After the specified number of seconds, the request will begin returning a 404 response for the object, and the objects are automatically deleted after some time.

If both headers are specified, the X-Delete-After header takes priority.

Header operation features:

  • if the object is uploaded using a PUT request with the X-Delete-At header, and the bucket has a modified header, the object header will be overwritten by the bucket header;
  • if versioning is enabled in the bucket, the X-Delete-At and X-Delete-After headers are not carried over to the created version. The uploaded version will not be removed, but the object will disappear from the list.

Segmented objects

There are no size restrictions on uploaded objects in the storage, but it is not recommended to place objects larger than 100 MB into the storage in one piece — you should break the object into segments, upload each segment of the object, and upload a manifest file that unites all segments of the object (DLO/SLO technology). More details on uploading segmented objects in the documentation guide Upload an object.

When using segmented upload, you can upload two types of large objects:

  • dynamic (DLO), when uploading a dynamic object manifest, you need to specify the bucket and segment prefix. You can upload and remove individual segments without needing to change the manifest file;
  • static (SLO), when uploading a static object manifest, specify the path to each segment of which the object consists. Each time segments are changed, you must edit and upload the manifest file again. Optionally, for segments, you can specify their checksums (Etag) and size.

To get the manifest file, perform a GET request to retrieve the object with the query parameter ?multipart-manifest=get.

You can remove all segments and the object with the manifest using a DELETE request with the query parameter ?multipart-manifest=delete.

Upload object segments

We recommend uploading segments first, and then creating or updating the manifest. Until all segments are uploaded, the object will not be available for download.

Request examples

curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "hello " \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000001'

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "world" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000002'

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "!" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000003'

Response example

On success, the requests return responses with code 201.

Upload a dynamic object manifest

Request example

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Object-Manifest: <bucket_name>/<object_name>/' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'

Response example

On success, the request returns a response with code 201.

Upload a static object manifest

Request example

In the body of the static object manifest, specify the path to each object segment.

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Static-Large-Object: True' \
-d "[{"path": "/<bucket_name>/<object_name>/00000001"}, {"path": "/<bucket_name>/<object_name>/00000002"}, {"path": "/<bucket_name>/<object_name>/00000003"} ...]" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>?multipart-manifest=put'

Response example

On success, the request returns a response with code 201.

Limits

POST/v1/ {project_id} /{bucket_name}Set bucket limits
POST/v1/ {project_id}Set project limits

Set bucket limits

Sets restrictions on a bucket, passed in the X-Container-Meta-Quota-Bytes and X-Container-Meta-Quota-Count. headers.

Request headers

HeaderDescription
X-Container-Meta-Quota-BytesMaximum storage capacity (in bytes)
X-Container-Meta-Quota-CountMaximum number of objects in the bucket
X-Container-Meta-Default-Delete-AfterRetention period for all objects in the bucket (in seconds). After this period, objects will be automatically removed

Request example

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Quota-Bytes: 52428800' \
-H 'X-Container-Meta-Quota-Count: 1000' \
-H 'X-Container-Meta-Default-Delete-After: 300' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'

Response example

On successful request execution, a response with code 202 will be returned.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

Set project limits

Sets a restriction on a project, passed in the X-Account-Meta-Quota-Bytes. header.

Request headers

HeaderDescription
X-Container-Meta-Quota-BytesMaximum storage capacity (in bytes)

Request example

curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Account-Meta-Quota-Bytes: 52428800' \
'https://<swift_domain>/v1/<project_id>'

Response example

On successful request execution, a response with code 202 will be returned.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

Additional query parameters

In a request to get a list of buckets or objects, you can use additional query parameters.

format

Returns a list of objects in a specific format.

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?format=json'

The list of objects will be returned in JSON format.

limit

Sets the exact number of objects that will be included in the list (for example, when working with buckets that store a large number of objects).

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?limit=20'

The first 20 objects will be included in the list.

marker

Sets the object from which the list will be displayed.

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?marker=<object_name>'

The list will display objects that follow the object <object_name>.

prefix

Includes objects in the list whose names start with the specified sequence of characters.

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?prefix=my'

The list will display objects that start with the characters my.

delimiter

S3 has a flat structure and does not support folders, but with the delimiter parameter, you can display a pseudo-hierarchy. A request with this parameter will output only the part of the object name that follows the specified characters, if it is present in the object name output.

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?delimiter=/'

Files and parts of prefixes (pseudo-folders) at the top level will be displayed:

photos/
videos/
file.jpg

Where:

  • photos/, videos/ — prefix parts up to the / character, which are present in the objects in the bucket;
  • file.jpg — file without a prefix (the / character in the name).

The delimiter parameter can be used together with the prefix parameter to output a list of objects and pseudo-folders by the specified prefix.

Request example:

curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?prefix=photos/&delimiter=/'

Output example:

photos/animals/
photos/file.jpg

A symbolic link is an empty object that points to another object. They can be used to access objects in another bucket:

  • with a different storage policy — for example, to access an object in a cold storage bucket from a standard storage bucket;
  • with a different type — for example, to access an object in a private bucket through a symbolic link placed in a public bucket.

You can create a symbolic link with an empty PUT request to upload an object with the X-Symlink-Target: <bucket_name>/<object_name>. header;.

By default, symbolic links are dynamic — they point to an object by its name. A symbolic link can be made static: when following the link, the Etag of the object is additionally checked. To do this, add the header X-Symlink-Target-Etag: <etag> to the request;.

If the symbolic link object is not empty, the request will return response 400.

To get an object with a symbolic link, perform a GET or HEAD request with the ?symlink=get. parameter.