Swift API

Open in Markdown

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 the project in S3; for more details, see the Manage S3 access instructions.

Authorization

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

You can find the address (URL) 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 ID. You can find the ID in the Control panel under S3 → project menu → Project management. The ID is displayed under the project name.

Storage

HEAD	/v1/ {project_id}	Get storage info
GET	/v1/ {project_id}	Get storage info and bucket list
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

Parameter	Value
X-Account-Bytes-Used	Total volume of stored data (in bytes)
X-Account-Container-Count	Number of buckets
X-Account-Meta-<...>	Metadata, where <...> is a custom header
X-Account-Meta-Temp-Url-Key	Secret key used to access objects in a private bucket via a temporary URL (if available)
X-Account-Object-Count	Total number of stored objects
X-Account-Storage-Policy-Policy-0-Bytes-Used	Total volume of stored data by storage policy, where Policy-0 — policy name
X-Account-Storage-Policy-Policy-0-Container-Count	Number of buckets using a storage policy, where Policy-0 — policy name
X-Account-Storage-Policy-Policy-0-Object-Count	Number of objects using a storage policy, where Policy-0 — policy name
X-Openstack-Request-Id X-Trans-Id	Request ID
X-Timestamp	Date and time in UNIX format when the account, bucket, or object was created
Date	Date 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 returns 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

Header	Description
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 list of bucket objects and metadata
PUT	/v1/ {project_id} / {bucket_name}	Create bucket
POST	/v1/ {project_id} / {bucket_name}	Manage bucket metadata
DELETE	/v1/ {project_id} / {bucket_name}	Delete 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 returns 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

Parameter	Value
X-Container-Object-Count	Number of objects in the bucket
X-Container-Bytes-Used	Volume of objects in the bucket (in bytes)
X-Container-Meta-Type	Bucket type
X-Container-Meta-Quota-Bytes	Maximum storage capacity (in bytes)
X-Container-Meta-Quota-Count	Maximum number of objects in the bucket
X-Container-Meta-<...>	Bucket metadata, where <...> is a custom header
X-Versions-Enabled	Whether bucket versioning is enabled

Create a bucket

Creates a bucket with the parameters specified in the request.

Request headers

Header	Description
X-Container-Meta-Type	public (public); private (private) Bucket type:
X-Container-Meta-<...>	Bucket metadata. Specify \\<...> — metadata header
X-Storage-Policy	Storage class: Policy-0 (default) — standard storage
X-Versions-Enabled	Whether bucket versioning is enabled
X-Container-Meta-Default-Delete-After	Storage duration of 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

If successful, the request returns a 201 response.

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

Header	Description
X-Container-Meta-Type	public; private Bucket type:
X-Container-Meta-<...>	Bucket metadata to be set, where <...> is a custom header
X-Remove-Container-Meta-<...>	Bucket metadata to be deleted, where <...> is a custom header
X-Versions-Enabled	Whether bucket versioning is enabled

Request example

Changing 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

If successful, the request returns a 204 response.

Delete bucket

Deletes a bucket in the storage. Delete all objects in the bucket before deleting it.

Request example

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

Response example

If successful, the request returns a 204 response.

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 object
POST	/v1/ {project_id}	Delete multiple objects
POST	/v1/ {project_id} / {bucket_name} / {object_name}	Manage object HTTP headers and metadata
COPY	/v1/ {project_id} / {bucket_name} / {object_name}	Copy object
DELETE	/v1/ {project_id} / {bucket_name} / {object_name}	Delete object

Get object

Returns the body and headers of an object.

Request example

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

Response example

If successful, the request returns a 200 response.

Upload object

Uploads an object to the bucket. This upload method 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 the 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

Header	Description
X-Delete-At	Object deletion time in Unix timestamp format
X-Delete-After	Object storage duration (in seconds)
Etag	Etag identifier
X-Object-Meta-<...>	Object metadata, where <...> is a custom header
X-Copy-From	Path to the object to be copied

Request example

Uploading 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> — name to be assigned to the object.

Copying 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> — bucket to copy the object to;
• <object_name_2> — name with which the object will be copied;
• <bucket_name_1> — bucket containing the object to be copied;
• <object_name_1> — object to be copied.

Response example

When uploading an object, if successful, the request returns a 201 response.

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, if successful, the request returns a 201 response.

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

Deletes multiple objects at the same time, including objects from different buckets. Objects are deleted sequentially.

Request example

Deleting 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

If successful, the request returns a 200 response.

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 object HTTP headers and metadata

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

Supported HTTP headers:

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

Request headers

Header	Description
X-Container-Meta-<...>	Header whose parameters need to be set. Specify <...> — header (for example, X-Container-Meta-Cache-Control)

Request example

Adding the Link header to the 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 202 response if successful.

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

A request to add a custom header returns a 201 response if successful.

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

Copy object

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

Request headers

Header	Description
Destination	Path 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> — bucket containing the object to be copied;
• <object_name_1> — object to be copied.
• <bucket_name_2> — bucket to copy the object to;
• <object_name_2> — name with which the object will be copied.

Response example

If successful, the request returns a 201 response.

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 object

The object will be deleted from the bucket.

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

Request example

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

Response example

If successful, the request returns a 204 response.

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

Headers for deferred deletion

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

Header	Value	Description
X-Delete-At	Timestamp value in Unix Epoch format	The server will store the object until the time passed in the header. To convert to a human-readable format, you can use EpochConverter.
X-Delete-After	Integer number of seconds	The server converts this value into the X-Delete-At header. After the specified number of seconds, requests to the object will start returning a 404 response, while objects are automatically deleted after some time.

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

Header specifics:

• if an 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 with the bucket header;
• if versioning is enabled on the bucket, the X-Delete-At and X-Delete-After headers are not transferred to the created version. The uploaded version will not be deleted, but the object will disappear from the list.

Segmented objects

There are no restrictions on the size of uploaded objects in the storage, but it is not recommended to store objects larger than 100 MB as a single entity — you should split the object into segments, upload each segment of the object and a manifest file combining all object segments (DLO/SLO technology). For details on uploading segmented objects, see the documentation instructions Upload object.

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

• dynamic (DLO), when uploading a dynamic object manifest, specify the bucket and segment prefix. You can upload and delete individual segments without modifying the manifest file;
• static (SLO), when uploading a static object manifest, specify the path to each segment that makes up the object. Each time segments change, you must edit and re-upload the manifest file. Optionally, you can specify segment checksums (Etag) and size.

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

You can delete 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

If successful, the requests return 201 responses.

Upload 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

If successful, the request returns a 201 response.

Upload static object manifest

Request example

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

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

If successful, the request returns a 201 response.

Limits

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

Set bucket limits

Sets bucket limits passed in the X-Container-Meta-Quota-Bytes and X-Container-Meta-Quota-Count headers.

Request headers

Header	Description
X-Container-Meta-Quota-Bytes	Maximum data storage volume (in bytes)
X-Container-Meta-Quota-Count	Maximum number of objects in the bucket
X-Container-Meta-Default-Delete-After	Storage duration of all objects in the bucket (in seconds). After this duration expires, objects will be automatically deleted

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

If the request is successful, a 202 response is returned.

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

Set project limits

Sets project limits passed in the X-Account-Meta-Quota-Bytes header.

Request headers

Header	Description
X-Container-Meta-Quota-Bytes	Maximum data storage volume (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

If the request is successful, a 202 response is returned.

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

Additional query parameters

You can use additional query parameters in requests to get a list of buckets or objects.

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 object list will be returned in JSON format.

limit

Specifies the exact number of objects to include 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 list will include the first 20 objects.

marker

Specifies the object starting 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 after the object <object_name>.

prefix

Includes in the list objects 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 using the delimiter parameter, you can display a pseudo-hierarchy. A request with this parameter returns only the part of the object names that precedes the specified character, if 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 prefix parts (pseudo-folders) at the top level will be displayed:

photos/
videos/
file.jpg

Where:

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

The delimiter parameter can be used together with the prefix parameter to list 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

Symbolic links

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, access an object in a cold storage bucket from a standard storage bucket;
• with a different type — for example, access an object in a private bucket via a symbolic link placed in a public bucket.

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

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

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

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