Swift

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

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

To access the Swift API, the user must have a role with access to the project in S3, more details in the documentation instructions Manage Access in S3.

Authorization

Authorization in the Swift API is done using the IAM token for the project, which is passed in each request in the X-Auth-Token header.

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

An example query to view the list of bucket list 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 the project;
<swift_domain> — Swift API domain в pool where S3 is located;
<project_id> — project identifier. You can view the ID in control panel under S3 → project menu → Project Management. The identifier is listed under the project name.

Storage

HEAD	/v1/ {project_id}	Obtaining storage information
GET	/v1/ {project_id}	Obtaining information about the storage and the list of bins
POST	/v1/ {project_id}	Storage metadata management

Get storage information

Returns metadata with information about the number and storage capacity of bins and objects.

Example request

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

Example answer

If successful, 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	Significance
X-Account-Bytes-Used.	Total amount of data stored (in bytes)
X-Account-Container-Count	Number of bins
X-Account-Meta-<...>	Metadata where <...> — custom header
X-Account-Meta-Temp-Url-Key	The secret key that is used to access objects in the 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	The total amount of data stored by storage policy, where Policy-0 is the name of the policy
X-Account-Storage-Policy-Policy-0-Container-Count	The number of buckets that use the storage policy, where Policy-0 is the policy name
X-Account-Storage-Policy-Policy-0-Object-Count	The number of objects that use the storage policy, where Policy-0 is the policy name
X-Openstack-Request-Id. X-Trans-Id	request ID
X-Timestamp	The 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 the list of bucket list

Returns storage information and a list of bucket list.

One query outputs a list that can contain up to 10,000 bucket list. If there are more bucket list, use additional queries with query-parameter marker.

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

Example request

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

Example answer

bucket1
bucket2
bucket3

Manage storage metadata

Sets, replaces, or removes the metadata passed in the header from the request.

Request headers

Caption	Description
X-Account-Meta-<...>	Storage metadata to be set where <...> — custom header
X-Remove-Account-Meta-<...>	Storage metadata that needs to be deleted where <...> — custom header

Example request

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

Example answer

If successful, the request returns a response with code 204.

Buckets

HEAD	/v1/ {project_id} /{bucket_name}	Obtaining baket metadata
GET	/v1/ {project_id} /{bucket_name}	Obtaining the list of objects and baket metadata
PUT	/v1/ {project_id} /{bucket_name}	Creating a bucket
POST	/v1/ {project_id} /{bucket_name}	Baket metadata management
DELETE	/v1/ {project_id} /{bucket_name}	Bacet removal

Get baket metadata

Outputs bucket metadata, including number of objects, storage capacity (in bytes), and bucket headers.

Example request

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

Example answer

If successful, the request returns a response with code 204.

Get the list of objects and metadata of the baket

Returns the bucket metadata and outputs a list of objects.

One query outputs a list that can contain up to 10,000 objects. If there are more objects, use additional queries with query-parameters marker and limit.

Example request

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

Example answer

If successful, the query returns a response with a 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	Significance
X-Container-Object-Count	Number of objects in a batch
X-Container-Bytes-Used.	Volume of objects in the batch (in bytes)
X-Container-Meta-Type	Type of tank
X-Container-Meta-Quota-Bytes	Maximum data storage capacity (in bytes)
X-Container-Meta-Quota-Count.	Maximum number of objects in a package
X-Container-Meta-<... ...>	Baket metadata where <...> — custom header
X-Versions-Enabled	Whether versioning of the baket is enabled

Create a bucket

Creates a bucket with the parameters specified in the request.

Request headers

Caption	Description
X-Container-Meta-Type	public; private Buckett Type:
X-Container-Meta-<...>	Bucket metadata. Specify \\<...> — metadata header
X-Storage-Policy	Policy-0 (default) is the default storage; cold storage Storage Class:
X-Versions-Enabled	Whether versioning of the baket is enabled
X-Container-Meta-Default-Delete-After.	Storage time of all objects in the batch (in seconds)

Example request

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>'

Example answer

If successful, the query 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 baket metadata

Sets, replaces, or removes the metadata passed in the header from the request.

Request headers

Caption	Description
X-Container-Meta-Type	public; private Buckett Type:
X-Container-Meta-<...>	The bucket metadata to be set where<...> — custom header
X-Remove-Container-Meta-<... ...>	Buckett metadata that needs to be deleted where <...> — custom header
X-Versions-Enabled	Whether versioning of the baket is enabled

Example request

Change in bacta 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>'

Example answer

If successful, the request returns a response with code 204.

Remove the bucket

Deletes a baket in the storage. Before deleting a bucket, delete all objects in it.

Example request

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

Example answer

If successful, 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}	Obtaining an object
PUT	/v1/ {project_id} /{bucket_name} /{object_name}	Loading an object
POST	/v1/ {project_id}	Deleting multiple objects
POST	/v1/ {project_id} /{bucket_name} /{object_name}	Managing HTTP headers and object metadata
COPY	/v1/ {project_id} /{bucket_name} /{object_name}	Copying an object
DELETE	/v1/ {project_id} /{bucket_name} /{object_name}	Deleting an object

Get object

Outputs the body and headers of the object.

Example request

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

Example answer

If successful, the query returns a response with code 200.

Load object

Loads the object into the bucket. This loading is used for objects up to 100 MB in size. For larger objects, use segmented loading.

When using the X-Copy-From header, you can load a copied object into a bucket. The object is copied together with the X-Delete-At header, regardless of where the header is set (to the object or to the sideboard).

Request headers

Caption	Description
X-Delete-At	Time of object deletion in Unix Timestamp format
X-Delete-After	Object storage time (in seconds)
Etag	Etag ID
X-Object-Meta-<...>	The metadata of the object, where <...> — custom header
X-Copy-From	Path to the object to be copied

Example request

Loading 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 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 which the object will be copied;
<object_name_2> — the name with which the object will be copied;
<bucket_name_1> — the bucket in which the object to be copied is located;
<object_name_1> — object to be copied.

Example answer

When loading an object, if successful, 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, if successful, the query 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

Deletes several objects simultaneously, including objects from different bins. Objects are deleted sequentially.

Example request

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.

Example answer

If successful, the query 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 the user and HTTP headers specified in the request. Headers are used to control client-side caching and intermediate proxy servers.

Supported HTTP headers:

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

Request headers

Caption	Description
X-Container-Meta-<...>	The title whose parameters you want to set. Specify<...> — header (for example, X-Container-Meta-Cache-Control)

Example request

Adding a 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>'

Example answer

A request to add a Link header, if successful, returns a response with code 202.

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

The request to add a custom header, if successful, returns a response with code 201.

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 by a different prefix. If the X-Fresh-Metadata header is set to true, the new object will be created with new headers when copying, including without X-Delete-At.

Request headers

Caption	Description
Destination	Path where the object will be copied

Example request

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 in which the object to be copied is located;
<object_name_1> — object to be copied.
<bucket_name_2> — bucket to which the object will be copied;
<object_name_2> — the name with which the object will be copied.

Example answer

If successful, the query 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 object

The object will be removed from the bacta.

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

Example request

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

Example answer

If successful, 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 deferred deletion

Headers are specified when sending PUT and POST requests and determine when an object will be automatically removed from the repository.

Caption	Significance	Description
X-Delete-At	Timestamp value in Unix Epoch format	The server will store the object until the time passed in the header. EpochConverter can be used to convert to human-readable form.
X-Delete-After	Integer number of seconds	The server converts this value into an X-Delete-At header. After the specified number of seconds, the request will start returning a 404 response to the object request, with the objects automatically deleted after a certain amount of time.

If both headers are specified, the X-Delete-After header will be prioritized.

Features how headings work:

if the object is loaded with a PUT request and an 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 transferred to the created version. The loaded version will not be deleted, but the object will disappear from the list.

Segmented objects

There is no limit on the size of uploaded objects in the repository, but it is not recommended to put objects larger than 100 MB into the repository in their entirety — you should split the object into segments, upload each segment of the object and a manifest file uniting all segments of the object (DLO/SLO technology). For more information about uploading segmented objects, see the Upload Object documentation instructions.

When using segmented loading, two types of large objects can be loaded:

dynamic (DLO), when loading a dynamic object manifest, you must specify the bucket and prefix of the segments. You can load and delete individual segments without having to change the manifest file;
static (SLO), when loading the manifest of a static object, the path to each segment that makes up the object is specified. Each time the segments are changed, the manifest file must be edited and loaded again. Optionally, you can specify checksums (Etag) and size for segments.

To retrieve the manifest file, perform 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.

Load object segments

We recommend downloading segments first before creating or updating the manifest. Until all segments have finished downloading, the object will not be available for download.

Example of requests

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'

Example answer

If successful, the queries return responses with code 201.

Load the dynamic object manifest Example request

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>'

Example answer

If successful, the query returns a response with code 201.

Load a static object manifest Example request

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

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Static-Large-Object: True' \
"[{"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'

Example answer

If successful, the query returns a response with code 201.

Limits

POST	/v1/ {project_id} /{bucket_name}	Setting buckets limits
POST	/v1/ {project_id}	Setting project limits

Set buckets limits

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

Request headers

Caption	Description
X-Container-Meta-Quota-Bytes	Maximum data storage capacity (in bytes)
X-Container-Meta-Quota-Count.	Maximum number of objects in a package
X-Container-Meta-Default-Delete-After.	The retention period for all objects in the batch (in seconds). After this period expires, the objects will be automatically deleted

Example request

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>'

Example answer

If the request is successful, a response with code 202 will be returned.

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

Set project limits

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

Request headers

Caption	Description
X-Container-Meta-Quota-Bytes	Maximum data storage capacity (in bytes)

Example request

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

Example answer

If the request is successful, a response with code 202 will be returned.

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

Additional query parameters

You can use additional query-parameters in a query to retrieve a list of bucket list or objects.

format

Will return a list of objects in a specific format.

Example of a request:

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

Specifies the exact number of objects to be included in the list (e.g., when working with buckets that store a large number of objects).

Example of a request:

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

marker

Specifies the object starting from which the list will be displayed.

Example of a request:

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

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

prefix

Will include in the list objects whose names begin with the specified sequence of characters.

Example of a request:

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

The list will show 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 output a pseudo-hierarchy.A query with the parameter will output only the part of the object name that follows before the specified characters, if present in the object name output.

Example of a request:

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

The files and parts of the prefixes (pseudo folders) at the top level will be output:

photos/
videos/
file.jpg

Here:

photos/, videos/ — prefixes before the character / that the objects in the baguette have;
file.jpg — file without prefix (symbol / in the name).

The delimiter parameter can be used in conjunction with the prefix parameter to list objects and pseudo-folders by the specified prefix.

Example of a request:

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

Example output:

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

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

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

If the referenced object is non-empty, the query will return a response of 400.

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