Swift Object Storage REST APIs

Auth URL

A client can use the Swift auth URL to authenticate as a tenant account user.

https://FQDN:Swift_Port/auth/v1.0/
You must provide the tenant account ID, user name, and password as parameters in the X-Auth-User and X-Auth-Key request headers, as follows:

  • X-Auth-User: <Tenant_ID>:<User_Name>
  • X-Auth-Key: <Your_Password>
curl -X GET -i https://api-object.bluvalt.com:8083/auth/v1.0/ -H "X-Auth-User: <Tenant_ID>:<User_Name>" -H "X-Auth-Key: <Your_Password>"

The response to a successful authentication request returns a storage URL and an auth token, as follows:

  • X-Storage-Url: https://FQDN:Swift_Port/v1/<Tenant_ID>
  • X-Auth-Token: <Your_Obtained_AUTH_Token>
  • X-Storage-Token: token

By default, the token is valid for 24 hours from generation time.

Tokens are generated for a specific tenant account. A valid token for one account does not authorize a user to access another account.

Example: This example demonstrates obtaining an auth TOKEN for a specific Tenant and User Name.

Tenant_ID: 62704805254211618615
User_Name: test Password: 1234567890

curl -X GET -i https://api-object.bluvalt.com:8083/auth/v1.0/ -H "X-Auth-User: 62704805254211618615:test" -H "X-Auth-Key: 1234567890"

Response

HTTP/1.1 204 No Content
Date: Wed, 03 Apr 2019 07:43:50 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553794844406610
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Storage-Url: https://api-object.bluvalt.com:8083/v1/62704805254211618615
X-Storage-Token: SGRD_70b2b45cbc0e414ea07251b8066c2ab9
X-Timestamp: 1554277430.277956
X-Auth-Token: SGRD_70b2b45cbc0e414ea07251b8066c2ab9

Storage URL

A client application can issue Swift REST API calls to perform supported account, container, and object operations against an API Gateway Node or Storage Node. Storage requests are addressed to the storage URL returned in the authentication response. The request must also include the X-Auth-Token header and value returned from the auth request.

https://FQDN:Swift_Port/v1/<Tenant_ID>[/container][/object]

Required Parameter

  • Account
  • Object

Required Header

  • X-Auth-Token: <Your_Obtained_AUTH_Token>
curl -X PUT -i 'https://api-object.bluvalt.com:8083/v1/<Tenant_ID>/<Test_Container>' -H "X-Auth-Token: <Your_Obtained_AUTH_Token>"

curl -X PUT -i 'https://api-object.bluvalt.com:8083/v1/<Tenant_ID>/<Test_Container>/<Test_Object>' -H "X-Auth-Token: <Your_Obtained_AUTH_Token>"

Some storage response headers that contain usage statistics might not reflect accurate numbers for recently modified objects. It might take a few minutes for accurate numbers to appear in these headers.

The following response headers for account and container operations are examples of those that contain usage statistics:

  • X-Account-Bytes-Used
  • X-Account-Object-Count
  • X-Container-Bytes-Used
  • X-Container-Object-Count

Example: This example demonstrates creating a new container from the storage URL

Tenant_ID: 62704805254211618615 The Account Parameter Test_Container: testcontainer X-Auth-Token: SGRD_70b2b45cbc0e414ea07251b8066c2ab9

curl -X PUT -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer' -H "X-Auth-Token: SGRD_70b2b45cbc0e414ea07251b8066c2ab9"

Response

HTTP/1.1 202 Accepted
Date: Wed, 03 Apr 2019 07:54:14 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553798640440063
Content-Length: 76
Content-Type: text/html; charset=UTF-8

<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html>

Account Operations

The following Swift API operations are performed on accounts.

GET account This operation retrieves the container list associated with the account and account usage statistics.

The following request parameter is required:

  • Account

The following request header is required:

  • X-Auth-Token

The following supported request query parameters are optional:

  • Delimiter
  • End_marker
  • Format
  • Limit
  • Marker
  • Prefix

A successful execution returns the following headers with an “HTTP/1.1 204 No Content” response if the account is found and has no containers or the container list is empty; or an “HTTP/1.1 200 OK” response if the account is found and the container list is not empty:

  • Accept-Ranges
  • Content-Length
  • Content-Type
  • Date
  • X-Account-Bytes-Used
  • X-Account-Container-Count
  • X-Account-Object-Count
  • X-Timestamp
  • X-Trans-Id
curl -X GET -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 200 OK
Date: Mon, 08 Apr 2019 11:38:55 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1554719213744724
Content-Length: 44
Accept-Ranges: bytes
Content-Type: text/plain; charset=utf-8
X-Account-Bytes-Used: 0
X-Account-Container-Count: 3
X-Account-Object-Count: 0
X-Timestamp: 1554194117.000000

testcontainer
testcontainer0
testcontainer1

HEAD account

This operation retrieves account information and statistics from a Swift account.

The following request parameter is required:

  • Account

The following request header is required:

  • X-Auth-Token

A successful execution returns the following headers with an “HTTP/1.1 204 No Content” response:

  • Accept-Ranges
  • Content-Length
  • Date
  • X-Account-Bytes-Used
  • X-Account-Container-Count
  • X-Account-Object-Count
  • X-Timestamp
  • X-Trans-Id
curl -X HEAD -I 'https://api-object.bluvalt.com:8083/v1/62704805254211618615' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 204 No Content
Date: Mon, 08 Apr 2019 11:41:44 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553802511053537
Content-Length: 0
Accept-Ranges: bytes
X-Account-Bytes-Used: 0
X-Account-Container-Count: 3
X-Account-Object-Count: 0
X-Timestamp: 1554194117.000000

Container operations

Object Storage supports a maximum of 1,000 containers per Swift account. The following Swift API operations are performed on containers.

DELETE container

This operation removes an empty container from a Swift account in the Object Storage. The following request parameters are required:

  • Account
  • Container

The following request header is required:

  • X-Auth-Token

A successful execution returns the following headers with an “HTTP/1.1 204 No Content” response:

  • Content-Length
  • Content-Type
  • Date
  • X-Trans-Id
curl -X DELETE -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer1' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 204 No Content
Date: Mon, 08 Apr 2019 11:44:39 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553802511053758
Content-Length: 0

GET container

This operation retrieves the object list associated with the container along with container statistics and metadata in the Object Storage system.

The following request parameters are required:

  • Account
  • Container

The following request header is required:

  • X-Auth-Token

The following supported request query parameters are optional:

  • Delimiter
  • End_marker
  • Format
  • Limit
  • Marker
  • Path
  • Prefix

A successful execution returns the following headers with an “HTTP/1.1 200 Success” or a “HTTP/1.1 204 No Content” response:

  • Accept-Ranges
  • Content-Length
  • Content-Type
  • Date
  • X-Container-Bytes-Used
  • X-Container-Object-Count
  • X-Timestamp
  • X-Trans-Id
curl -X GET -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 204 No Content
Date: Mon, 08 Apr 2019 11:46:06 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553798643143136
Content-Length: 0
Accept-Ranges: bytes
Content-Type: text/plain; charset=utf-8
X-Container-Bytes-Used: 0
X-Container-Object-Count: 0
X-Timestamp: 1554211225.378156

HEAD container

This operation retrieves container statistics and metadata from a Object Storage system. The following request parameters are required:

  • Account
  • Container

The following request header is required:

  • X-Auth-Token

A successful execution returns the following headers with an “HTTP/1.1 204 No Content” response:

  • Accept-Ranges
  • Content-Length
  • Date
  • X-Container-Bytes-Used
  • X-Container-Object-Count
  • X-Timestamp
  • X-Trans-Id
curl -X HEAD -I 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer' -H "X-
Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 204 No Content
Date: Mon, 08 Apr 2019 11:47:48 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553798643143730
Content-Length: 0
Accept-Ranges: bytes
X-Container-Bytes-Used: 0
X-Container-Object-Count: 0
X-Timestamp: 1554211225.378156

PUT container

This operation creates a container for an account in the Object Storage system. The following request parameters are required:

  • Account
  • Container

The following request header is required:

  • X-Auth-Token

A successful execution returns the following headers with an “HTTP/1.1 201 Created” or “HTTP/1.1 202 Accepted” (if the container already exists under this account) response: Content-Length

  • Date
  • X-Timestamp
  • X-Trans-Id

A container name must be unique in the Object Storage namespace. If the container exists under another account, the following header is returned: “HTTP/1.1 409 Conflict.”

curl -X PUT -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer3' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 201 Created
Date: Mon, 08 Apr 2019 11:49:34 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553802511054182
Content-Length: 0
X-Timestamp: 1554724174.429611

Object Operations

The following Swift API operations are performed on objects.

DELETE object

This operation deletes an object’s content and metadata from the Object Storage system.

The following request parameters are required:

  • Account
  • Container
  • Object

The following request header is required:

  • X-Auth-Token

A successful execution returns the following response headers with an “HTTP/1.1 204 No Content” response:

  • Content-Length
  • Content-Type
  • Date
  • X-Trans-Id
curl -X DELETE -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer3/testobject.txt' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 204 No Content
Date: Mon, 08 Apr 2019 12:00:16 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553802511055091
Content-Length: 0

GET object

This operation retrieves the object content and gets the object metadata from a Object Storage system.

The following request parameters are required:

  • Account
  • Container
  • Object

The following request header is required:

  • X-Auth-Token

The following request headers are optional:

  • Accept-Encoding
  • If-Match
  • If-Modified-Since
  • If-None-Match
  • If-Unmodified-Since
  • Range

A successful execution returns the following headers with an “HTTP/1.1 200 OK” response:

  • Accept-Ranges
  • Content-Length
  • Content-Type
  • Date
  • ETag
  • Last-Modified
  • X-Timestamp
  • X-Trans-Id
curl -X GET -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainerect0.txt'  -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 200 OK
Date: Mon, 08 Apr 2019 11:55:04 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553793552918718
Content-Length: 9
ETag: 1e2db57dd6527ad4f8f281ab028d2c70
Accept-Ranges: bytes
Last-Modified: Mon, 08 Apr 2019 11:53:49 GMT
X-Timestamp: 1554724429.342444
Content-Type: application/x-www-form-urlencoded

HEAD object

This operation retrieves metadata and properties of an ingested object from a Object Storage system.

The following request parameters are required:

  • Account
  • Container
  • Object

The following request header is required:

  • X-Auth-Token

A successful execution returns the following headers with an “HTTP/1.1 200 OK” response:

  • Accept-Ranges
  • Content-Length
  • Content-Type
  • Date
  • ETag
  • Last-Modified
  • X-Timestamp
  • X-Trans-Id
curl -X HEAD -I 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer3/testobject0.txt' -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 200 OK
Date: Mon, 08 Apr 2019 11:57:48 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553798643147256
Content-Length: 9
ETag: 1e2db57dd6527ad4f8f281ab028d2c70
Accept-Ranges: bytes
Last-Modified: Mon, 08 Apr 2019 11:53:49 GMT
X-Timestamp: 1554724429.342444
Content-Type: application/x-www-form-urlencoded

PUT Object

This operation creates a new object with data and metadata, or replaces an existing object with data and metadata in a Object Storage system.

Note: Object Storage supports objects up to 5 TB in size.

The following request parameters are required:

  • Account
  • Container
  • Object

The following request header is required:

  • X-Auth-Token

The following request headers are optional:

  • Content-Encoding
  • Content-Length
  • Content-Type
  • ETag
  • Transfer-Encoding
  • X-Object-Meta- (object-related metadata)

If you want to use the User Defined Creation Time option as the Reference Time for an ILM rule, you must store the value in a user-defined header named X-Object-Meta-Creation-Time. For example: X-Object-Meta-Creation-Time: 1443399726 This field is evaluated as seconds since January 1, 1970.

  • X-Storage-Class: reduced_redundancy

Specifies a single-commit ingest operation. Use this header to specify reduced_redundancy only if you need to limit redundant storage at the time of ingest and only if you are willing to risk the loss of object data. For example, you might lose data if the single copy is initially stored on a Storage Node that fails before ILM evaluation can occur.

Specifying reduced_redundancy only affects how many copies are created when an object is first ingested. It does not affect how many copies of the object are made when the object is evaluated by the active ILM policy. Using reduced_redundancy does not result in data being stored at lower levels of redundancy in the Object Storage system.

A successful execution returns the following headers with an “HTTP/1.1 201 Created” response:

  • Content-Length
  • Content-Type
  • Date
  • ETag
  • Last-Modified
  • X-Trans-Id
curl -X PUT -i 'https://api-object.bluvalt.com:8083/v1/62704805254211618615/testcontainer3/testobject0.txt' -d "test text" -H "X-Auth-Token: SGRD_6b9d0db2010b45039a32f090c922cad4"

HTTP/1.1 201 Created
Date: Mon, 08 Apr 2019 11:53:49 GMT
Connection: KEEP-ALIVE
X-Trans-Id: 1553802511054542
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Last-Modified: Mon, 08 Apr 2019 11:53:49 GMT
ETag: 1e2db57dd6527ad4f8f281ab028d2c70
X-Timestamp: 1554724429.321089