Object Storage API — swift documentation (original) (raw)

Object Storage API¶

Discoverability¶

If configured, lists the activated capabilities for this version of the OpenStack Object Storage API.

/info

List activated capabilities

Lists the activated capabilities for this version of the OpenStack Object Storage API.

Most of the information is “public” i.e. visible to all callers. However, some configuration and capability items are reserved for the administrators of the system. To access this data, the swiftinfo_sig and swiftinfo_expiresquery parameters must be added to the request.

Normal response codes: 200 Error response codes:

Request¶

Response Example¶

{ "swift": { "version": "1.11.0" }, "slo": { "max_manifest_segments": 1000, "max_manifest_size": 2097152, "min_segment_size": 1 }, "staticweb": {}, "tempurl": {} }

Accounts¶

Lists containers for an account. Creates, updates, shows, and deletes account metadata. For more information and concepts about accounts see Object Storage API overview.

/v1/{account}

Show account details and list containers

Shows details for an account and lists containers, sorted by name, in the account.

The sort order for the name is based on a binary comparison, a single built-in collating sequence that compares string data by using the SQLite memcmp() function, regardless of text encoding. See Collating Sequences.

The response body returns a list of containers. The default response (text/plain) returns one container per line.

If you use query parameters to page through a long list of containers, you have reached the end of the list if the number of items in the returned list is less than the request limitvalue. The list contains more items if the number of items in the returned list equals the limit value.

When asking for a list of containers and there are none, the response behavior changes depending on whether the request format is text, JSON, or XML. For a text response, you get a 204 , because there is no content. However, for a JSON or XML response, you get a 200 with content indicating an empty array.

Example requests and responses:

• Show account details and list containers and ask for a JSON response:
  curl -i publicURL?format=json−XGET−H"X−Auth−Token:publicURL?format=json -X GET -H "X-Auth-Token: publicURL?format=json−XGET−H"X−Auth−Token:token"
  HTTP/1.1 200 OK
  Content-Length: 96
  X-Account-Object-Count: 1
  X-Timestamp: 1389453423.35964
  X-Account-Meta-Subject: Literature
  X-Account-Bytes-Used: 14
  X-Account-Container-Count: 2
  Content-Type: application/json; charset=utf-8
  Accept-Ranges: bytes
  X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
  X-Openstack-Request-Id: tx274a77a8975c4a66aeb24-0052d95365
  Date: Fri, 17 Jan 2014 15:59:33 GMT
  [
  {
  "count": 0,
  "bytes": 0,
  "name": "janeausten",
  "last_modified": "2013-11-19T20:08:13.283452"
  },
  {
  "count": 1,
  "bytes": 14,
  "name": "marktwain",
  "last_modified": "2016-04-29T16:23:50.460230"
  }
  ]
• Show account details and list containers and ask for an XML response:
  curl -i publicURL?format=xml−XGET−H"X−Auth−Token:publicURL?format=xml -X GET -H "X-Auth-Token: publicURL?format=xml−XGET−H"X−Auth−Token:token"
  HTTP/1.1 200 OK
  Content-Length: 262
  X-Account-Object-Count: 1
  X-Timestamp: 1389453423.35964
  X-Account-Meta-Subject: Literature
  X-Account-Bytes-Used: 14
  X-Account-Container-Count: 2
  Content-Type: application/xml; charset=utf-8
  Accept-Ranges: bytes
  X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
  X-Openstack-Request-Id: tx69f60bc9f7634a01988e6-0052d9544b
  Date: Fri, 17 Jan 2014 16:03:23 GMT janeausten 0 0 2013-11-19T20:08:13.283452 marktwain 1 14 2016-04-29T16:23:50.460230

If the request succeeds, the operation returns one of these status codes:

• OK (200). Success. The response body lists the containers.
• No Content (204). Success. The response body shows no containers. Either the account has no containers or you are paging through a long list of names by using the marker,limit, or end_marker query parameter and you have reached the end of the list.

Normal response codes: 200 Error response codes:204,

Request¶

Response Parameters¶

/v1/{account}

Create, update, or delete account metadata

Creates, updates, or deletes account metadata.

To create, update, or delete custom metadata, use theX-Account-Meta-{name} request header, where {name} is the name of the metadata item.

Account metadata operations work differently than how object metadata operations work. Depending on the contents of your POST account metadata request, the Object Storage API updates the metadata as shown in the following table:

Account metadata operations

To delete a metadata header, send an empty value for that header, such as for the X-Account-Meta-Book header. If the tool you use to communicate with Object Storage, such as an older version of cURL, does not support empty headers, send the X-Remove-Account- Meta-{name} header with an arbitrary value. For example,X-Remove-Account-Meta-Book: x. The operation ignores the arbitrary value.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according toHTTP/1.1 . The underscore character is silently converted to a hyphen.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Subsequent requests for the same key and value pair overwrite the existing value.

If the container already has other custom metadata items, a request to create, update, or delete metadata does not affect those items.

This operation does not accept a request body.

Example requests and responses:

• Create account metadata:
  curl -i publicURL−XPOST−H"X−Auth−Token:publicURL -X POST -H "X-Auth-Token: publicURL−XPOST−H"X−Auth−Token:token" -H "X-Account-Meta-Book: MobyDick" -H "X-Account-Meta-Subject: Literature"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx8c2dd6aee35442a4a5646-0052d954fb
  X-Openstack-Request-Id: tx8c2dd6aee35442a4a5646-0052d954fb
  Date: Fri, 17 Jan 2014 16:06:19 GMT
• Update account metadata:
  curl -i publicURL−XPOST−H"X−Auth−Token:publicURL -X POST -H "X-Auth-Token: publicURL−XPOST−H"X−Auth−Token:token" -H "X-Account-Meta-Subject: AmericanLiterature"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx1439b96137364ab581156-0052d95532
  X-Openstack-Request-Id: tx1439b96137364ab581156-0052d95532
  Date: Fri, 17 Jan 2014 16:07:14 GMT
• Delete account metadata:
  curl -i publicURL−XPOST−H"X−Auth−Token:publicURL -X POST -H "X-Auth-Token: publicURL−XPOST−H"X−Auth−Token:token" -H "X-Remove-Account-Meta-Subject: x"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx411cf57701424da99948a-0052d9556f
  X-Openstack-Request-Id: tx411cf57701424da99948a-0052d9556f
  Date: Fri, 17 Jan 2014 16:08:15 GMT

If the request succeeds, the operation returns the No Content (204) response code.

To confirm your changes, issue a show account metadata request.

Error response codes:204,

Request¶

Response Parameters¶

/v1/{account}

Show account metadata

Shows metadata for an account.

Metadata for the account includes:

• Number of containers
• Number of objects
• Total number of bytes that are stored in Object Storage for the account

Because the storage system can store large amounts of data, take care when you represent the total bytes response as an integer; when possible, convert it to a 64-bit unsigned integer if your platform supports that primitive type.

Do not include metadata headers in this request.

Show account metadata request:

curl -i publicURL−XHEAD−H"X−Auth−Token:publicURL -X HEAD -H "X-Auth-Token: publicURL−XHEAD−H"X−Auth−Token:token"

HTTP/1.1 204 No Content Content-Length: 0 X-Account-Object-Count: 1 X-Account-Meta-Book: MobyDick X-Timestamp: 1389453423.35964 X-Account-Bytes-Used: 14 X-Account-Container-Count: 2 Content-Type: text/plain; charset=utf-8 Accept-Ranges: bytes X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4 X-Openstack-Request-Id: txafb3504870144b8ca40f7-0052d955d4 Date: Fri, 17 Jan 2014 16:09:56 GMT

If the account or authentication token is not valid, the operation returns the Unauthorized (401) response code.

Error response codes:204,401,

Request¶

Response Parameters¶

/v1/{account}

Delete the specified account

Deletes the specified account when a reseller admin issues this request. Accounts are only deleted by (1) having a reseller admin level auth token (2) sending a DELETE to a proxy server for the account to be deleted and (3) that proxy server having the allow_account_management” config option set to true.

Note that an issuing a DELETE request simply marks the account for deletion later as outlined in the link: https://docs.openstack.org/swift/latest/overview_reaper.html.

Take care when performing this operation because deleting an account is a one-way operation that is not trivially recoverable. It’s crucial to note that in an OpenStack context, you should delete an account after the project/tenant has been deleted from Keystone.

curl -i publicURL−XDELETE−H′X−Auth−Token:publicURL -X DELETE -H 'X-Auth-Token: publicURL−XDELETE−H′X−Auth−Token:'

HTTP/1.1 204 No Content Content-Length: 0 Content-Type: text/html; charset=UTF-8 X-Account-Status: Deleted X-Trans-Id: tx91ce60a640cc42eca198a-006128c180 X-Openstack-Request-Id: tx91ce60a640cc42eca198a-006128c180 Date: Fri, 27 Aug 2021 11:42:08 GMT

If the account or authentication token is not valid, the operation returns the Unauthorized (401). If you try to delete an account with a non-admin token, a 403 Forbidden response code is returned. If you give a non-existent account or an invalid URL, a 404 Not Found response code is returned.

Error response codes:204,401,403,404.

Request¶

Response Parameters¶

Containers¶

Lists objects in a container. Creates, shows details for, and deletes containers. Creates, updates, shows, and deletes container metadata. For more information and concepts about containers see Object Storage API overview.

/v1/{account}/{container}

Show container details and list objects

Shows details for a container and lists objects, sorted by name, in the container.

Specify query parameters in the request to filter the list and return a subset of objects. Omit query parameters to return a list of objects that are stored in the container, up to 10,000 names. The 10,000 maximum value is configurable. To view the value for the cluster, issue a GET /info request.

Example requests and responses:

• OK (200). Success. The response body lists the objects.
• No Content (204). Success. The response body shows no objects. Either the container has no objects or you are paging through a long list of objects by using the marker, limit, orend_marker query parameter and you have reached the end of the list.

If the container does not exist, the call returns the Not Found (404) response code.

Normal response codes: 200, 204

Error response codes: 404

Request¶

Response Parameters¶

Response Example format=json¶

HTTP/1.1 200 OK Content-Length: 341 X-Container-Object-Count: 2 Accept-Ranges: bytes X-Container-Meta-Book: TomSawyer X-Timestamp: 1389727543.65372 X-Container-Bytes-Used: 26 Content-Type: application/json; charset=utf-8 X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff X-Openstack-Request-Id: tx26377fe5fab74869825d1-0052d6bdff Date: Wed, 15 Jan 2014 16:57:35 GMT

[ { "hash": "451e372e48e0f6b1114fa0724aa79fa1", "last_modified": "2014-01-15T16:41:49.390270", "bytes": 14, "name": "goodbye", "content_type": "application/octet-stream" }, { "hash": "ed076287532e86365e841e92bfc50d8c", "last_modified": "2014-01-15T16:37:43.427570", "bytes": 12, "name": "helloworld", "content_type": "application/octet-stream" } ]

Response Example format=xml¶

HTTP/1.1 200 OK Content-Length: 500 X-Container-Object-Count: 2 Accept-Ranges: bytes X-Container-Meta-Book: TomSawyer X-Timestamp: 1389727543.65372 X-Container-Bytes-Used: 26 Content-Type: application/xml; charset=utf-8 X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76 X-Openstack-Request-Id: txc75ea9a6e66f47d79e0c5-0052d6be76 Date: Wed, 15 Jan 2014 16:59:35 GMT

/v1/{account}/{container}

Create container

Creates a container.

You do not need to check whether a container already exists before issuing a PUT operation because the operation is idempotent: It creates a container or updates an existing container, as appropriate.

To create, update, or delete a custom metadata item, use the X -Container-Meta-{name} header, where {name} is the name of the metadata item.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according toHTTP/1.1 . The underscore character is silently converted to a hyphen.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Example requests and responses:

• Create a container with no metadata:
  curl -i publicURL/steven−XPUT−H"Content−Length:0"−H"X−Auth−Token:publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: publicURL/steven−XPUT−H"Content−Length:0"−H"X−Auth−Token:token"
  HTTP/1.1 201 Created
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
  X-Openstack-Request-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
  Date: Tue, 14 Jan 2014 19:09:10 GMT
• Create a container with metadata:
  curl -i publicURL/marktwain−XPUT−H"X−Auth−Token:publicURL/marktwain -X PUT -H "X-Auth-Token: publicURL/marktwain−XPUT−H"X−Auth−Token:token" -H "X-Container-Meta-Book: TomSawyer"
  HTTP/1.1 201 Created
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
  X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
  Date: Tue, 14 Jan 2014 19:25:43 GMT
• Create a container with an ACL to allow anybody to get an object in the marktwain container:
  curl -i publicURL/marktwain−XPUT−H"X−Auth−Token:publicURL/marktwain -X PUT -H "X-Auth-Token: publicURL/marktwain−XPUT−H"X−Auth−Token:token" -H "X-Container-Read: .r:*"
  HTTP/1.1 201 Created
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
  X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
  Date: Tue, 14 Jan 2014 19:25:43 GMT

Normal response codes: 201, 202

Error response codes: 400, 404, 507

Request¶

Response Parameters¶

/v1/{account}/{container}

Create, update, or delete container metadata

Creates, updates, or deletes custom metadata for a container.

To create, update, or delete a custom metadata item, use the X -Container-Meta-{name} header, where {name} is the name of the metadata item.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according toHTTP/1.1 . The underscore character is silently converted to a hyphen.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Subsequent requests for the same key and value pair overwrite the previous value.

To delete container metadata, send an empty value for that header, such as for the X-Container-Meta-Book header. If the tool you use to communicate with Object Storage, such as an older version of cURL, does not support empty headers, send the X-Remove- Container-Meta-{name} header with an arbitrary value. For example, X-Remove-Container-Meta-Book: x. The operation ignores the arbitrary value.

If the container already has other custom metadata items, a request to create, update, or delete metadata does not affect those items.

Example requests and responses:

• Create container metadata:
  curl -i publicURL/marktwain−XPOST−H"X−Auth−Token:publicURL/marktwain -X POST -H "X-Auth-Token: publicURL/marktwain−XPOST−H"X−Auth−Token:token" -H "X-Container-Meta-Author: MarkTwain" -H "X-Container-Meta-Web-Directory-Type: text/directory" -H "X-Container-Meta-Century: Nineteenth"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx05dbd434c651429193139-0052d82635
  X-Openstack-Request-Id: tx05dbd434c651429193139-0052d82635
  Date: Thu, 16 Jan 2014 18:34:29 GMT
• Update container metadata:
  curl -i publicURL/marktwain−XPOST−H"X−Auth−Token:publicURL/marktwain -X POST -H "X-Auth-Token: publicURL/marktwain−XPOST−H"X−Auth−Token:token" -H "X-Container-Meta-Author: SamuelClemens"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653
  X-Openstack-Request-Id: txe60c7314bf614bb39dfe4-0052d82653
  Date: Thu, 16 Jan 2014 18:34:59 GMT
• Delete container metadata:
  curl -i publicURL/marktwain−XPOST−H"X−Auth−Token:publicURL/marktwain -X POST -H "X-Auth-Token: publicURL/marktwain−XPOST−H"X−Auth−Token:token" -H "X-Remove-Container-Meta-Century: x"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0
  X-Openstack-Request-Id: tx7997e18da2a34a9e84ceb-0052d826d0
  Date: Thu, 16 Jan 2014 18:37:04 GMT

If the request succeeds, the operation returns the No Content (204) response code.

To confirm your changes, issue a show container metadata request.

Normal response codes: 204

Error response codes: 404

Request¶

Response Parameters¶

/v1/{account}/{container}

Show container metadata

Shows container metadata, including the number of objects and the total bytes of all objects stored in the container.

Show container metadata request:

curl -i publicURL/marktwain−XHEAD−H"X−Auth−Token:publicURL/marktwain -X HEAD -H "X-Auth-Token: publicURL/marktwain−XHEAD−H"X−Auth−Token:token"

HTTP/1.1 204 No Content Content-Length: 0 X-Container-Object-Count: 1 Accept-Ranges: bytes X-Container-Meta-Book: TomSawyer X-Timestamp: 1389727543.65372 X-Container-Meta-Author: SamuelClemens X-Container-Bytes-Used: 14 Content-Type: text/plain; charset=utf-8 X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2 X-Openstack-Request-Id: tx0287b982a268461b9ec14-0052d826e2 Date: Thu, 16 Jan 2014 18:37:22 GMT

If the request succeeds, the operation returns the No Content (204) response code.

Normal response codes: 204

Request¶

Response Parameters¶

/v1/{account}/{container}

Delete container

Deletes an empty container.

This operation fails unless the container is empty. An empty container has no objects.

Delete the steven container:

curl -i publicURL/steven−XDELETE−H"X−Auth−Token:publicURL/steven -X DELETE -H "X-Auth-Token: publicURL/steven−XDELETE−H"X−Auth−Token:token"

If the container does not exist, the response is:

HTTP/1.1 404 Not Found Content-Length: 70 Content-Type: text/html; charset=UTF-8 X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34 X-Openstack-Request-Id: tx4d728126b17b43b598bf7-0052d81e34 Date: Thu, 16 Jan 2014 18:00:20 GMT

If the container exists and the deletion succeeds, the response is:

HTTP/1.1 204 No Content Content-Length: 0 Content-Type: text/html; charset=UTF-8 X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14 X-Openstack-Request-Id: txf76c375ebece4df19c84c-0052d81f14 Date: Thu, 16 Jan 2014 18:04:04 GMT

If the container exists but is not empty, the response is:

HTTP/1.1 409 Conflict Content-Length: 95 Content-Type: text/html; charset=UTF-8 X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b X-Openstack-Request-Id: tx7782dc6a97b94a46956b5-0052d81f6b Date: Thu, 16 Jan 2014 18:05:31 GMT

Conflict

There was a conflict when trying to complete your request.

Normal response codes: 204

Error response codes: 404, 409

Request¶

Response Parameters¶

Objects¶

Creates, replaces, shows details for, and deletes objects. Copies objects from another object with a new or different name. Updates object metadata. For more information and concepts about objects see Object Storage API overviewand Large Objects.

/v1/{account}/{container}/{object}

Get object content and metadata

Downloads the object content and gets the object metadata.

This operation returns the object metadata in the response headers and the object content in the response body.

If this is a large object, the response body contains the concatenated content of the segment objects. To get the manifest instead of concatenated segment objects for a static large object, use the multipart-manifest query parameter.

Example requests and responses:

• Show object details for the goodbye object in themarktwain container:
  curl -i publicURL/marktwain/goodbye−XGET−H"X−Auth−Token:publicURL/marktwain/goodbye -X GET -H "X-Auth-Token: publicURL/marktwain/goodbye−XGET−H"X−Auth−Token:token"
  HTTP/1.1 200 OK
  Content-Length: 14
  Accept-Ranges: bytes
  Last-Modified: Wed, 15 Jan 2014 16:41:49 GMT
  Etag: 451e372e48e0f6b1114fa0724aa79fa1
  X-Timestamp: 1389804109.39027
  X-Object-Meta-Orig-Filename: goodbyeworld.txt
  Content-Type: application/octet-stream
  X-Trans-Id: tx8145a190241f4cf6b05f5-0052d82a34
  X-Openstack-Request-Id: tx8145a190241f4cf6b05f5-0052d82a34
  Date: Thu, 16 Jan 2014 18:51:32 GMT
  Goodbye World!
• Show object details for the goodbye object, which does not exist, in the janeausten container:
  curl -i publicURL/janeausten/goodbye−XGET−H"X−Auth−Token:publicURL/janeausten/goodbye -X GET -H "X-Auth-Token: publicURL/janeausten/goodbye−XGET−H"X−Auth−Token:token"
  HTTP/1.1 404 Not Found
  Content-Length: 70
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx073f7cbb850c4c99934b9-0052d82b04
  X-Openstack-Request-Id: tx073f7cbb850c4c99934b9-0052d82b04
  Date: Thu, 16 Jan 2014 18:55:00 GMT

  Not Found

  The resource could not be found.

The operation returns the Range Not Satisfiable (416) response code for any ranged GET requests that specify more than:

• Fifty ranges.
• Three overlapping ranges.
• Eight non-increasing ranges.

Normal response codes: 200

Error response codes: 416, 404

Request¶

Response Parameters¶

Response Example¶

See examples above.

/v1/{account}/{container}/{object}

Create or replace object

Creates an object with data content and metadata, or replaces an existing object with data content and metadata.

The PUT operation always creates an object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns the Created (201) response code.

If you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB.

Note that the provider may have limited the characters which are allowed in an object name. Any name limits are exposed under the name_check key in the /info discoverability response. Regardless of name_checklimitations, names must be URL quoted UTF-8.

To create custom metadata, use theX-Object-Meta-name header, where name is the name of the metadata item.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according toHTTP/1.1 . The underscore character is silently converted to a hyphen.

Example requests and responses:

• Create object:
  curl -i publicURL/janeausten/helloworld.txt−XPUT−d"Hello"−H"Content−Type:text/html;charset=UTF−8"−H"X−Auth−Token:publicURL/janeausten/helloworld.txt -X PUT -d "Hello" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: publicURL/janeausten/helloworld.txt−XPUT−d"Hello"−H"Content−Type:text/html;charset=UTF−8"−H"X−Auth−Token:token"
  HTTP/1.1 201 Created
  Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
  Content-Length: 0
  Etag: 8b1a9953c4611296a827abf8c47804d7
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
  X-Openstack-Request-Id: tx4d5e4f06d357462bb732f-0052d96843
  Date: Fri, 17 Jan 2014 17:28:35 GMT
• Replace object:
  curl -i publicURL/janeausten/helloworld.txt−XPUT−d"Hola"−H"X−Auth−Token:publicURL/janeausten/helloworld.txt -X PUT -d "Hola" -H "X-Auth-Token: publicURL/janeausten/helloworld.txt−XPUT−d"Hola"−H"X−Auth−Token:token"
  HTTP/1.1 201 Created
  Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
  Content-Length: 0
  Etag: f688ae26e9cfa3ba6235477831d5122e
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
  X-Openstack-Request-Id: tx4d5e4f06d357462bb732f-0052d96843
  Date: Fri, 17 Jan 2014 17:28:35 GMT

The Created (201) response code indicates a successful write.

If the container for the object does not already exist, the operation returns the 404 Not Found response code.

If the request times out, the operation returns the Request Timeout (408) response code.

The Length Required (411) response code indicates a missingTransfer-Encoding or Content-Length request header.

If the MD5 checksum of the data that is written to the object store does not match the optional ETag value, the operation returns the Unprocessable Entity (422) response code.

Normal response codes: 201

Error response codes: 404, 408, 411, 422

Request¶

Response Parameters¶

/v1/{account}/{container}/{object}

Copy object

Copies an object to another object in the object store.

You can copy an object to a new object with the same name. Copying to the same name is an alternative to using POST to add metadata to an object. With POST, you must specify all the metadata. With COPY, you can add additional metadata to the object.

With COPY, you can set the X-Fresh-Metadata header to trueto copy the object without any existing metadata.

Alternatively, you can use PUT with the X-Copy-From request header to accomplish the same operation as the COPY object operation.

The COPY operation always creates an object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns the Created (201) response code.

Normally, if you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB in size.

To copy the manifest object, you include themultipart-manifest=get query string in the COPY request. The new object contains the same manifest as the original. The segment objects are not copied. Instead, both the original and new manifest objects share the same set of segment objects.

To copy a symlink either with a COPY or a PUT with theX-Copy-From request, include the symlink=get query string. The new symlink will have the same target as the original. The target object is not copied. Instead, both the original and new symlinks point to the same target object.

All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) object.

Example requests and responses:

• Copy the goodbye object from the marktwain container to the janeausten container:
  curl -i publicURL/marktwain/goodbye−XCOPY−H"X−Auth−Token:publicURL/marktwain/goodbye -X COPY -H "X-Auth-Token: publicURL/marktwain/goodbye−XCOPY−H"X−Auth−Token:token" -H "Destination: janeausten/goodbye"
  HTTP/1.1 201 Created
  Content-Length: 0
  X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
  X-Copied-From: marktwain/goodbye
  Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
  Etag: 451e372e48e0f6b1114fa0724aa79fa1
  Content-Type: text/html; charset=UTF-8
  X-Object-Meta-Movie: AmericanPie
  X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
  X-Openstack-Request-Id: txdcb481ad49d24e9a81107-0052d97501
  Date: Fri, 17 Jan 2014 18:22:57 GMT
• Alternatively, you can use PUT to copy the goodbye object from the marktwain container to the janeausten container. This request requires a Content-Length header, even if it is set to zero (0).
  curl -i publicURL/janeausten/goodbye−XPUT−H"X−Auth−Token:publicURL/janeausten/goodbye -X PUT -H "X-Auth-Token: publicURL/janeausten/goodbye−XPUT−H"X−Auth−Token:token" -H "X-Copy-From: /marktwain/goodbye" -H "Content-Length: 0"
  HTTP/1.1 201 Created
  Content-Length: 0
  X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
  X-Copied-From: marktwain/goodbye
  Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
  Etag: 451e372e48e0f6b1114fa0724aa79fa1
  Content-Type: text/html; charset=UTF-8
  X-Object-Meta-Movie: AmericanPie
  X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
  X-Openstack-Request-Id: txdcb481ad49d24e9a81107-0052d97501
  Date: Fri, 17 Jan 2014 18:22:57 GMT

When several replicas exist, the system copies from the most recent replica. That is, the COPY operation behaves as though theX-Newest header is in the request.

Normal response codes: 201

Request¶

Response Parameters¶

/v1/{account}/{container}/{object}

Delete object

Permanently deletes an object from the object store.

Object deletion occurs as soon as possible. Subsequent GET, HEAD, POST, or DELETE operations should return a 404 Not Found error code, but may return stale data due to eventual consistency.

For static large object manifests, you can add the?multipart-manifest=delete query parameter. This operation deletes the segment objects and, if all deletions succeed, this operation deletes the manifest object.

A DELETE request made to a symlink path will delete the symlink rather than the target object.

An alternative to using the DELETE operation is to use the POST operation with the bulk-delete query parameter.

Example request and response:

• Delete the helloworld object from the marktwain container:
  curl -i publicURL/marktwain/helloworld−XDELETE−H"X−Auth−Token:publicURL/marktwain/helloworld -X DELETE -H "X-Auth-Token: publicURL/marktwain/helloworld−XDELETE−H"X−Auth−Token:token"
  HTTP/1.1 204 No Content
  Content-Length: 0
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
  X-Openstack-Request-Id: tx36c7606fcd1843f59167c-0052d6fdac
  Date: Wed, 15 Jan 2014 21:29:16 GMT

Typically, the DELETE operation does not return a response body. However, with the multipart-manifest=delete query parameter, the response body contains a list of manifest and segment objects and the status of their DELETE operations.

Normal response codes: 204

Request¶

Response Parameters¶

/v1/{account}/{container}/{object}

Show object metadata

Shows object metadata.

Example requests and responses:

• Show object metadata:
  curl publicURL/marktwain/goodbye−−head−H"X−Auth−Token:publicURL/marktwain/goodbye --head -H "X-Auth-Token: publicURL/marktwain/goodbye−−head−H"X−Auth−Token:token"
  HTTP/1.1 200 OK
  Content-Length: 14
  Accept-Ranges: bytes
  Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT
  Etag: 451e372e48e0f6b1114fa0724aa79fa1
  X-Timestamp: 1389906751.73463
  X-Object-Meta-Book: GoodbyeColumbus
  Content-Type: application/octet-stream
  X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
  X-Openstack-Request-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
  Date: Thu, 16 Jan 2014 21:13:19 GMT
  Note: The --head option was used in the above example. If we had used -i -X HEAD and the Content-Length response header is non-zero, the cURL command stalls after it prints the response headers because it is waiting for a response body. However, the Object Storage system does not return a response body for the HEAD operation.

If the request succeeds, the operation returns the 200 response code.

Normal response codes: 200

Request¶

Response Parameters¶

Response Example¶

See examples above.

/v1/{account}/{container}/{object}

Create or update object metadata

Creates or updates object metadata.

To create or update custom metadata, use theX-Object-Meta-name header, where name is the name of the metadata item.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according toHTTP/1.1 . The underscore character is silently converted to a hyphen.

In addition to the custom metadata, you can update theContent-Type, Content-Encoding, Content-Disposition, andX-Delete-At system metadata items. However you cannot update other system metadata, such as Content-Length or Last-Modified.

You can use COPY as an alternate to the POST operation by copying to the same object. With the POST operation you must specify all metadata items, whereas with the COPY operation, you need to specify only changed or additional items. All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) object.

Note

While using COPY instead of POST allows sending only a subset of the metadata, it carries the cost of reading and rewriting the entire contents of the object.

A POST request deletes any existing custom metadata that you added with a previous PUT or POST request. Consequently, you must specify all custom metadata in the request. However, system metadata is unchanged by the POST request unless you explicitly supply it in a request header.

You can also set the X-Delete-At or X-Delete-After header to define when to expire the object.

When used as described in this section, the POST operation creates or replaces metadata. This form of the operation has no request body. There are alternate uses of the POST operation as follows:

• You can also use the form POST feature to upload objects.
• The POST operation when used with the bulk-delete query parameter can be used to delete multiple objects and containers in a single operation.
• The POST operation when used with the extract-archive query parameter can be used to upload an archive (tar file). The archive is then extracted to create objects.

A POST request must not include X-Symlink-Target header. If it does then a 400 status code is returned and the object metadata is not modified.

When a POST request is sent to a symlink, the metadata will be applied to the symlink, but the request will result in a 307 Temporary Redirect response to the client. The POST is never redirected to the target object, thus a GET/HEAD request to the symlink without symlink=get will not return the metadata that was sent as part of the POST request.

Example requests and responses:

• Create object metadata:
  curl -i publicURL/marktwain/goodbye−XPOST−H"X−Auth−Token:publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: publicURL/marktwain/goodbye−XPOST−H"X−Auth−Token:token" -H "X-Object-Meta-Book: GoodbyeColumbus"
  HTTP/1.1 202 Accepted
  Content-Length: 76
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
  X-Openstack-Request-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
  Date: Thu, 16 Jan 2014 21:12:31 GMT

  Accepted

  The request is accepted for processing.

• Update object metadata:
  curl -i publicURL/marktwain/goodbye−XPOST−H"X−Auth−Token:publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: publicURL/marktwain/goodbye−XPOST−H"X−Auth−Token:token" -H "X-Object-Meta-Book: GoodbyeOldFriend"
  HTTP/1.1 202 Accepted
  Content-Length: 76
  Content-Type: text/html; charset=UTF-8
  X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
  X-Openstack-Request-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
  Date: Thu, 16 Jan 2014 21🔞28 GMT

  Accepted

  The request is accepted for processing.

Normal response codes: 202

Request¶

Response Parameters¶

Endpoints¶

If configured, lists endpoints for an account.

/v1/endpoints

List endpoints

Lists endpoints for an object, account, or container.

When the cloud provider enables middleware to list the/endpoints/ path, software that needs data location information can use this call to avoid network overhead. The cloud provider can map the /endpoints/ path to another resource, so this exact resource might vary from provider to provider. Because it goes straight to the middleware, the call is not authenticated, so be sure you have tightly secured the environment and network when using this call.

Error response codes:201,

Request¶

This operation does not accept a request body.