Object Storage API

Object Storage API

Accounts

Lists containers for an account. Creates, updates, shows, and deletes account metadata.

Account metadata operations work differently than container and object metadata operations work. Depending on the contents of your POST account metadata request, the Object Storage API updates the metadata in one of these ways:

Account metadata operations

POST request body contains Description

A metadata key without a value.

The metadata key already exists for the account.

The API removes the metadata item from the account.

A metadata key without a value.

The metadata key does not already exist for the account.

The API ignores the metadata key.

A metadata key value.

The metadata key already exists for the account.

The API updates the metadata key value for the account.

A metadata key value.

The metadata key does not already exist for the account.

The API adds the metadata key and value pair, or item, to the account.

One or more account metadata items are omitted.

The metadata items already exist for the account.

The API does not change the existing metadata items.

For these requests, specifying the X-Remove-Account-Meta-* request header for the key with any value is equivalent to specifying the X-Account-Meta-* request header with an empty value.

Metadata keys 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 to HTTP/1.1 . Also, Object Storage does not support the underscore character, which it silently converts to a hyphen.

The metadata values in Object Storage do not follow HTTP/1.1 rules for character encodings. You must use a UTF-8 encoding to get a byte array for any string that contains characters that are not in the 7-bit ASCII 0-127 range. Otherwise, Object Storage returns the 404 response code for ISO-8859-1 characters in the 128-255 range, which is a direct violation of the HTTP/1.1 basic rules.

GET
/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.

Example requests and responses:

  • Show account details and list containers and ask for a JSON response:

    curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"
    
  • List containers and ask for an XML response:

    curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"
    

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 limit value. 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.

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

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
limit (Optional) query integer For an integer value n , limits the number of results to n .
marker (Optional) query string For a string value, x , returns container names that are greater than the marker value.
end_marker (Optional) query string For a string value, x , returns container names that are less than the marker value.
format (Optional) query string The response format. Valid values are json, xml, or plain. The default is plain. If you append the format=xml or format=json query parameter to the storage account URL, the response shows extended container information serialized in that format. If you append the format=plain query parameter, the response lists the container names separated by newlines.
prefix (Optional) query string Prefix value. Named items in the response begin with this value.
delimiter (Optional) query string Delimiter value, which returns the object names that are nested in the container. If you do not set a prefix and set the delimiter to “/” you may get unexpected results where all the objects are returned instead of only those with the delimiter set.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
Accept (Optional) header string Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Account-Meta-name (Optional) header string The custom account metadata item, where {name} is the name of the metadata item. One X-Account- Meta- {name} response header appears for each metadata item (for each {name}).
X-Account-Object-Count header integer The number of objects in the account.
X-Account-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. If not set, this header is not returned in the response. The second key enables you to rotate keys by having two active keys at the same time.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Account-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Account-Bytes-Used header integer The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count header integer The number of containers.
Content-Type (Optional) header string Changes the MIME type for the object.
count body integer The number of objects in the container.
bytes body integer The total number of bytes that are stored in Object Storage for the account.
name body string The name of the container.

Response Example

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
Date: Fri, 17 Jan 2014 16:03:23 GMT
POST
/v1/{account}

Create, update, or delete account metadata

Creates, updates, or deletes account metadata.

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

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

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.

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 -X POST -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
    Date: Fri, 17 Jan 2014 16:06:19 GMT
    
  • Update account metadata:

    curl -i $publicURL -X POST -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
    Date: Fri, 17 Jan 2014 16:07:14 GMT
    
  • Delete account metadata:

    curl -i $publicURL -X POST -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
    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

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Account-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. If not set, this header is not returned in the response. The second key enables you to rotate keys by having two active keys at the same time.
X-Account-Meta-name (Optional) header string The custom account metadata item, where {name} is the name of the metadata item. One X-Account- Meta- {name} response header appears for each metadata item (for each {name}).
Content-Type (Optional) header string Changes the MIME type for the object.
X-Detect-Content-Type (Optional) header boolean If set to true, Object Storage guesses the content type based on the file extension and ignores the value sent in the Content- Type header, if present.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
HEAD
/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 -X HEAD -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
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

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Account-Meta-name (Optional) header string The custom account metadata item, where {name} is the name of the metadata item. One X-Account- Meta- {name} response header appears for each metadata item (for each {name}).
X-Account-Object-Count header integer The number of objects in the account.
X-Account-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. If not set, this header is not returned in the response. The second key enables you to rotate keys by having two active keys at the same time.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Account-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Account-Bytes-Used header integer The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count header integer The number of containers.
Content-Type (Optional) header string Changes the MIME type for the object.

Endpoints

If configured, lists endpoints for an account.

GET
/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.

Objects

Creates, replaces, shows details for, and deletes objects. Copies objects from another object with a new or different name. Updates object metadata.

GET
/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 the marktwain container:

    curl -i $publicURL/marktwain/goodbye -X GET -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
    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 -X GET -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
    Date: Thu, 16 Jan 2014 18:55:00 GMT
    <html>
    <h1>Not Found
    </h1>
    <p>The resource could not be found.
    </p>
    </html>
    

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

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
temp_url_sig query string Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires query integer The date and time in UNIX Epoch time stamp format when the signature for temporary URLs expires. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT. For more information about temporary URLs, see Temporary URL middleware.
filename (Optional) query string Overrides the default file name. Object Storage generates a default file name for GET temporary URLs that is based on the object name. Object Storage returns this value in the Content-Disposition response header. Browsers can interpret this file name value as a file attachment to save. For more information about temporary URLs, see Temporary URL middleware.
multipart-manifest (Optional) query string If you include the multipart-manifest=get query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the X-Object-Manifest response header for dynamic large objects or in the response body for static large objects.
Range (Optional) header string The ranges of content to get. You can use the Range header to get portions of data by using one or more range specifications. To specify many ranges, separate the range specifications with a comma. The types of range specifications are: - Byte range specification. Use FIRST_BYTE_OFFSET to specify the start of the data range, and LAST_BYTE_OFFSET to specify the end. You can omit the LAST_BYTE_OFFSET and if you do, the value defaults to the offset of the last byte of data. - Suffix byte range specification. Use LENGTH bytes to specify the length of the data range. The following forms of the header specify the following ranges of data: - Range: bytes=-5. The last five bytes. - Range: bytes=10-15. The five bytes of data after a 10-byte offset. - Range: bytes=10-15,-5. A multi- part response that contains the last five bytes and the five bytes of data after a 10-byte offset. The Content-Type response header contains multipart/byteranges. - Range: bytes=4-6. Bytes 4 to 6 inclusive. - Range: bytes=2-2. Byte 2, the third byte of the data. - Range: bytes=6-. Byte 6 and after. - Range: bytes=1-3,2-5. A multi-part response that contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The Content-Type response header contains multipart/byteranges.
If-Match (Optional) header string See Request for Comments: 2616.
If-None-Match (Optional) header string In combination with Expect: 100-Continue, specify an "If- None-Match: *" header to query whether the server already has a copy of the object before any data is sent.
If-Modified-Since (Optional) header string See Request for Comments: 2616.
If-Unmodified-Since (Optional) header string See Request for Comments: 2616.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
Content-Disposition (Optional) header string If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional) header string If set, the value of the Content-Encoding metadata.
X-Delete-At (Optional) header integer The date and time in UNIX Epoch time stamp format when the system removes the object. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Accept-Ranges header string The type of ranges that the object accepts.
X-Object-Manifest (Optional) header string Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
Last-Modified header string

The date and time when the object was created or its metadata was changed.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

ETag header string The MD5 checksum of the copied object content. The value is not quoted.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Static-Large-Object header boolean Set to true if this object is a static large object manifest object.
Content-Type (Optional) header string Changes the MIME type for the object.

Response Example

See examples above.

PUT
/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.

Example requests and responses:

  • Create object:

    curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -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: 116
    Etag: d41d8cd98f00b204e9800998ecf8427e
    Content-Type: text/html; charset=UTF-8
    X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
    Date: Fri, 17 Jan 2014 17:28:35 GMT
    
  • Replace object:

    curl -i $publicURL/janeausten/helloworld -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
    
    HTTP/1.1 201 Created
    Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
    Content-Length: 116
    Etag: d41d8cd98f00b204e9800998ecf8427e
    Content-Type: text/html; charset=UTF-8
    X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
    Date: Fri, 17 Jan 2014 17:28:35 GMT
    

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

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

The Length Required (411) response code indicates a missing Transfer-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.

Error response codes:201,422,411,408,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
multipart-manifest (Optional) query string If ?multipart-manifest=put, the object is a static large object manifest and the body contains the manifest.
temp_url_sig query string Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires query integer The date and time in UNIX Epoch time stamp format when the signature for temporary URLs expires. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT. For more information about temporary URLs, see Temporary URL middleware.
filename (Optional) query string Overrides the default file name. Object Storage generates a default file name for GET temporary URLs that is based on the object name. Object Storage returns this value in the Content-Disposition response header. Browsers can interpret this file name value as a file attachment to save. For more information about temporary URLs, see Temporary URL middleware.
X-Object-Manifest (Optional) header string Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Transfer-Encoding (Optional) header string Set to chunked to enable chunked transfer encoding. If used, do not set the Content-Length header to a non-zero value.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Detect-Content-Type (Optional) header boolean If set to true, Object Storage guesses the content type based on the file extension and ignores the value sent in the Content- Type header, if present.
X-Copy-From (Optional) header string If set, this is the name of an object used to create the new object by copying the X-Copy-From object. The value is in form {container}/{object}. You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using PUT with X-Copy-From has the same effect as using the COPY operation to copy an object. Using Range header with X-Copy-From will create a new partial copied object with bytes set by Range.
ETag header string The MD5 checksum of the copied object content. The value is not quoted.
Content-Disposition (Optional) header string If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional) header string If set, the value of the Content-Encoding metadata.
X-Delete-At (Optional) header integer The date and time in UNIX Epoch time stamp format when the system removes the object. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Delete-After (Optional) header integer The number of seconds after which the system removes the object. Internally, the Object Storage system stores this value in the X -Delete-At metadata item.
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
If-None-Match (Optional) header string In combination with Expect: 100-Continue, specify an "If- None-Match: *" header to query whether the server already has a copy of the object before any data is sent.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
ETag header string The MD5 checksum of the copied object content. The value is not quoted.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

Content-Type (Optional) header string Changes the MIME type for the object.
last_modified body string

The date and time when the object was last modified.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

COPY
/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 true to 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 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 in size. 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 -X COPY -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
    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 -X PUT -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
    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 the X-Newest header is in the request.

Error response codes:201,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
Destination header string The container and object name of the destination object in the form of /container/object. You must UTF-8-encode and then URL-encode the names of the destination container and object before you include them in this header.
Content-Type (Optional) header string Changes the MIME type for the object.
Content-Encoding (Optional) header string If set, the value of the Content-Encoding metadata.
Content-Disposition (Optional) header string If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
X-Fresh-Metadata (Optional) header boolean Enables object creation that omits existing user metadata. If set to true, the COPY request creates an object without existing user metadata. Default value is false.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
X-Copied-From-Last-Modified (Optional) header integer For a copied object, the date and time in UNIX Epoch time stamp format when the container and object name from which the new object was copied was last modified. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Copied-From (Optional) header string For a copied object, shows the container and object name from which the new object was copied. The value is in the {container}/{object} format.
Last-Modified header string

The date and time when the object was created or its metadata was changed.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

ETag header string The MD5 checksum of the copied object content. The value is not quoted.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

Content-Type (Optional) header string Changes the MIME type for the object.
DELETE
/v1/{account}/{container}/{object}

Delete object

Permanently deletes an object from the object store.

You can use the COPY method to copy the object to a new location. Then, use the DELETE method to delete the original object.

Object deletion occurs immediately at request time. Any subsequent GET , HEAD , POST , or DELETE operations return a 404 Not Found error code.

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.

Example request and response:

  • Delete the helloworld object from the marktwain container:

    curl -i $publicURL/marktwain/helloworld -X DELETE -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
    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.

Error response codes:204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
multipart-manifest (Optional) query string If ?multipart-manifest=put, the object is a static large object manifest and the body contains the manifest.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
HEAD
/v1/{account}/{container}/{object}

Show object metadata

Shows object metadata.

If the Content-Length response header is non-zero, the example 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.

Example requests and responses:

  • Show object metadata:

    curl -i $publicURL/marktwain/goodbye -X 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
    Date: Thu, 16 Jan 2014 21:13:19 GMT
    

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

Normal response codes: 200 Error response codes:204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
temp_url_sig query string Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires query integer The date and time in UNIX Epoch time stamp format when the signature for temporary URLs expires. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT. For more information about temporary URLs, see Temporary URL middleware.
filename (Optional) query string Overrides the default file name. Object Storage generates a default file name for GET temporary URLs that is based on the object name. Object Storage returns this value in the Content-Disposition response header. Browsers can interpret this file name value as a file attachment to save. For more information about temporary URLs, see Temporary URL middleware.
multipart-manifest (Optional) query string If you include the multipart-manifest=get query parameter and the object is a large object, the object metadata is not returned. Instead, the response headers will include the manifest metadata and for dynamic large objects the X-Object-Manifest response header.
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Last-Modified header string

The date and time when the object was created or its metadata was changed.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
Content-Disposition (Optional) header string If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional) header string If set, the value of the Content-Encoding metadata.
X-Delete-At (Optional) header integer The date and time in UNIX Epoch time stamp format when the system removes the object. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Object-Manifest (Optional) header string Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
Last-Modified header string

The date and time when the object was created or its metadata was changed.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

ETag header string The MD5 checksum of the copied object content. The value is not quoted.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Static-Large-Object header boolean Set to true if this object is a static large object manifest object.
Content-Type (Optional) header string Changes the MIME type for the object.

Response Example

See examples above.

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

Create or update object metadata

Creates or updates object metadata.

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

In addition to the custom metadata, you can update the Content- Type, Content-Encoding, Content-Disposition, and X -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.

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.

You can also use the form POST feature to upload objects.

Example requests and responses:

  • Create object metadata:

    curl -i $publicURL/marktwain/goodbye -X POST -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
    Date: Thu, 16 Jan 2014 21:12:31 GMT
    <html>
    <h1>Accepted
    </h1>
    <p>The request is accepted for processing.
    </p>
    </html>
    
  • Update object metadata:

    curl -i $publicURL/marktwain/goodbye -X POST -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
    Date: Thu, 16 Jan 2014 21:18:28 GMT
    <html>
    <h1>Accepted
    </h1>
    <p>The request is accepted for processing.
    </p>
    </html>
    

Error response codes:202,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
object (Optional) path string The unique name for the object.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Object-Meta-name (Optional) header string The object metadata, where {name} is the name of the metadata item. You must specify an X-Object-Meta- {name} header for each metadata {name} item that you want to add or update.
X-Delete-At (Optional) header integer The date and time in UNIX Epoch time stamp format when the system removes the object. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Disposition (Optional) header string If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional) header string If set, the value of the Content-Encoding metadata.
X-Delete-After (Optional) header integer The number of seconds after which the system removes the object. Internally, the Object Storage system stores this value in the X -Delete-At metadata item.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Detect-Content-Type (Optional) header boolean If set to true, Object Storage guesses the content type based on the file extension and ignores the value sent in the Content- Type header, if present.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.

Containers

Lists objects in a container. Creates, shows details for, and deletes containers. Creates, updates, shows, and deletes container metadata.

GET
/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 object names. Omit query parameters to return the complete list of object names 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 names by using the marker, limit, or end_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.

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,204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
limit (Optional) query integer For an integer value n , limits the number of results to n .
marker (Optional) query string For a string value, x , returns container names that are greater than the marker value.
end_marker (Optional) query string For a string value, x , returns container names that are less than the marker value.
prefix (Optional) query string Prefix value. Named items in the response begin with this value.
format (Optional) query string The response format. Valid values are json, xml, or plain. The default is plain. If you append the format=xml or format=json query parameter to the storage account URL, the response shows extended container information serialized in that format. If you append the format=plain query parameter, the response lists the container names separated by newlines.
delimiter (Optional) query string Delimiter value, which returns the object names that are nested in the container. If you do not set a prefix and set the delimiter to “/” you may get unexpected results where all the objects are returned instead of only those with the delimiter set.
path (Optional) query string For a string value, returns the object names that are nested in the pseudo path.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
Accept (Optional) header string Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
X-Container-Meta-name (Optional) header string The container metadata, where {name} is the name of metadata item. You must specify an X-Container-Meta- {name} header for each metadata item (for each {name}) that you want to add or update.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Container-Object-Count header integer The number of objects.
Accept-Ranges header string The type of ranges that the object accepts.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Bytes-Used header integer The total number of bytes used.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

Content-Type (Optional) header string Changes the MIME type for the object.
hash body string The MD5 checksum value of the object content.
last_modified body string

The date and time when the object was last modified.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

bytes body integer The total number of bytes that are stored in Object Storage for the account.
name body string The name of the container.
content_type body string The content type of the object.

Response Example

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
Date: Wed, 15 Jan 2014 16:59:35 GMT
PUT
/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.

Example requests and responses:

  • Create a container with no metadata:

    curl -i $publicURL/steven -X PUT -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
    Date: Tue, 14 Jan 2014 19:09:10 GMT
    
  • Create a container with metadata:

    curl -i $publicURL/marktwain -X PUT -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
    Date: Tue, 14 Jan 2014 19:25:43 GMT
    

Error response codes:201,204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Container-Read (Optional) header string

Sets a container access control list (ACL) that grants read access. Container ACLs are available on any Object Storage cluster, and are enabled by container rather than by cluster.

To set the container read ACL:

$ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \
       "X-Container-Read: ACL" STORAGE_URL/CONTAINER

For example:

$ curl -X PUT -i \
       -H "X-Auth-Token: 0101010101" \
       -H "X-Container-Read: .r:*" \
       http://swift.example.com/v1/AUTH_bob/read_container

In the command, specify the ACL in the X-Container-Read header, as follows:

  • .r:* All referrers.
  • .r:example.com,swift.example.com Comma-separated list of referrers.
  • .rlistings Container listing access.
  • AUTH_username Access to a user who authenticates through a legacy or non-OpenStack-Identity-based authentication system.
  • LDAP_ Access to all users who authenticate through an LDAP- based legacy or non-OpenStack-Identity-based authentication system.
X-Container-Write (Optional) header string Sets an ACL that grants write access.
X-Container-Sync-To (Optional) header string Sets the destination for container synchronization. Used with the secret key indicated in the X -Container-Sync-Key header. If you want to stop a container from synchronizing, send a blank value for the X-Container-Sync-Key header.
X-Container-Sync-Key (Optional) header string Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted.
X-Versions-Location (Optional) header string The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If not set, versioning is disabled for this container. For more information about object versioning, see Object versioning.
X-Versions-Mode (Optional) header string The versioning mode for this container. The value must be either stack or history. If not set, stack mode will be used. This setting has no impact unless X-Versions-Location is set for the container. For more information about object versioning, see Object versioning.
X-Container-Meta-name (Optional) header string The container metadata, where {name} is the name of metadata item. You must specify an X-Container-Meta- {name} header for each metadata item (for each {name}) that you want to add or update.
X-Container-Meta-Access-Control-Allow-Origin (Optional) header string Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional) header string Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
X-Container-Meta-Access-Control-Expose-Headers (Optional) header string Headers the Object Storage service exposes to the browser (technically, through the user-agent setting), in the request response, separated by spaces. By default the Object Storage service returns the following values for this header: - All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. - The headers etag, x-timestamp, x-trans-id. - All metadata headers (X-Container-Meta-* for containers and X-Object- Meta-* for objects) headers listed in X-Container-   Meta- Access-Control-Expose-Headers.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Detect-Content-Type (Optional) header boolean If set to true, Object Storage guesses the content type based on the file extension and ignores the value sent in the Content- Type header, if present.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
POST
/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.

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 -X POST -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
    Date: Thu, 16 Jan 2014 18:34:29 GMT
    
  • Update container metadata:

    curl -i $publicURL/marktwain -X POST -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
    Date: Thu, 16 Jan 2014 18:34:59 GMT
    
  • Delete container metadata:

    curl -i $publicURL/marktwain -X POST -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
    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.

Error response codes:204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Container-Read (Optional) header string

Sets a container access control list (ACL) that grants read access. Container ACLs are available on any Object Storage cluster, and are enabled by container rather than by cluster.

To set the container read ACL:

$ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \
       "X-Container-Read: ACL" STORAGE_URL/CONTAINER

For example:

$ curl -X PUT -i \
       -H "X-Auth-Token: 0101010101" \
       -H "X-Container-Read: .r:*" \
       http://swift.example.com/v1/AUTH_bob/read_container

In the command, specify the ACL in the X-Container-Read header, as follows:

  • .r:* All referrers.
  • .r:example.com,swift.example.com Comma-separated list of referrers.
  • .rlistings Container listing access.
  • AUTH_username Access to a user who authenticates through a legacy or non-OpenStack-Identity-based authentication system.
  • LDAP_ Access to all users who authenticate through an LDAP- based legacy or non-OpenStack-Identity-based authentication system.
X-Remove-Container-name (Optional) header string Removes the metadata item named {name}. For example, X -Remove-Container-Read removes the X-Container- Read metadata item.
X-Container-Write (Optional) header string Sets an ACL that grants write access.
X-Container-Sync-To (Optional) header string Sets the destination for container synchronization. Used with the secret key indicated in the X -Container-Sync-Key header. If you want to stop a container from synchronizing, send a blank value for the X-Container-Sync-Key header.
X-Container-Sync-Key (Optional) header string Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted.
X-Versions-Location (Optional) header string The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If not set, versioning is disabled for this container. For more information about object versioning, see Object versioning.
X-Versions-Mode (Optional) header string The versioning mode for this container. The value must be either stack or history. If not set, stack mode will be used. This setting has no impact unless X-Versions-Location is set for the container. For more information about object versioning, see Object versioning.
X-Remove-Versions-Location (Optional) header string Set to any value to disable versioning.
X-Container-Meta-name (Optional) header string The container metadata, where {name} is the name of metadata item. You must specify an X-Container-Meta- {name} header for each metadata item (for each {name}) that you want to add or update.
X-Container-Meta-Access-Control-Allow-Origin (Optional) header string Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional) header string Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
X-Container-Meta-Access-Control-Expose-Headers (Optional) header string Headers the Object Storage service exposes to the browser (technically, through the user-agent setting), in the request response, separated by spaces. By default the Object Storage service returns the following values for this header: - All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. - The headers etag, x-timestamp, x-trans-id. - All metadata headers (X-Container-Meta-* for containers and X-Object- Meta-* for objects) headers listed in X-Container-   Meta- Access-Control-Expose-Headers.
X-Container-Meta-Quota-Bytes (Optional) header string Sets maximum size of the container, in bytes. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value.
X-Container-Meta-Quota-Count (Optional) header string Sets maximum object count of the container. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value.
X-Container-Meta-Web-Directory-Type (Optional) header string Sets the content-type of directory marker objects. If the header is not set, default is application/directory. Directory marker objects are 0-byte objects that represent directories to create a simulated hierarchical structure. For example, if you set "X-Container- Meta-Web-Directory- Type: text/directory", Object Storage treats 0-byte objects with a content-type of text/directory as directories rather than objects.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Detect-Content-Type (Optional) header boolean If set to true, Object Storage guesses the content type based on the file extension and ignores the value sent in the Content- Type header, if present.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
HEAD
/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 -X HEAD -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
Date: Thu, 16 Jan 2014 18:37:22 GMT

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

Error response codes:204,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Newest (Optional) header boolean If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
X-Container-Sync-Key (Optional) header string Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted.
X-Container-Meta-name (Optional) header string The container metadata, where {name} is the name of metadata item. You must specify an X-Container-Meta- {name} header for each metadata item (for each {name}) that you want to add or update.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Container-Object-Count header integer The number of objects.
X-Container-Write (Optional) header string Sets an ACL that grants write access.
X-Container-Meta-Quota-Count (Optional) header string Sets maximum object count of the container. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value.
Accept-Ranges header string The type of ranges that the object accepts.
X-Container-Read (Optional) header string

Sets a container access control list (ACL) that grants read access. Container ACLs are available on any Object Storage cluster, and are enabled by container rather than by cluster.

To set the container read ACL:

$ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \
       "X-Container-Read: ACL" STORAGE_URL/CONTAINER

For example:

$ curl -X PUT -i \
       -H "X-Auth-Token: 0101010101" \
       -H "X-Container-Read: .r:*" \
       http://swift.example.com/v1/AUTH_bob/read_container

In the command, specify the ACL in the X-Container-Read header, as follows:

  • .r:* All referrers.
  • .r:example.com,swift.example.com Comma-separated list of referrers.
  • .rlistings Container listing access.
  • AUTH_username Access to a user who authenticates through a legacy or non-OpenStack-Identity-based authentication system.
  • LDAP_ Access to all users who authenticate through an LDAP- based legacy or non-OpenStack-Identity-based authentication system.
X-Container-Meta-Access-Control-Expose-Headers (Optional) header string Headers the Object Storage service exposes to the browser (technically, through the user-agent setting), in the request response, separated by spaces. By default the Object Storage service returns the following values for this header: - All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. - The headers etag, x-timestamp, x-trans-id. - All metadata headers (X-Container-Meta-* for containers and X-Object- Meta-* for objects) headers listed in X-Container-   Meta- Access-Control-Expose-Headers.
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Bytes-Used header integer The total number of bytes used.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Container-Meta-Access-Control-Allow-Origin (Optional) header string Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional) header string Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Container-Sync-To (Optional) header string Sets the destination for container synchronization. Used with the secret key indicated in the X -Container-Sync-Key header. If you want to stop a container from synchronizing, send a blank value for the X-Container-Sync-Key header.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Container-Meta-Quota-Bytes (Optional) header string Sets maximum size of the container, in bytes. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value.
X-Versions-Location (Optional) header string The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If not set, versioning is disabled for this container. For more information about object versioning, see Object versioning.
X-Versions-Mode (Optional) header string The versioning mode for this container. The value must be either stack or history. If not set, stack mode will be used. This setting has no impact unless X-Versions-Location is set for the container. For more information about object versioning, see Object versioning.
DELETE
/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 -X DELETE -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
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
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
Date: Thu, 16 Jan 2014 18:05:31 GMT
<html>
<h1>Conflict
</h1>
<p>There was a conflict when trying to complete your request.
</p>
</html>

Error response codes:404,204,409,

Request

Name In Type Description
account (Optional) path string The unique name for the account. An account is also known as the project or tenant.
container (Optional) path string The unique name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (/) character because this character delimits the container and object name. For example, /account/container/object.
X-Auth-Token (Optional) header string Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Container-Meta-Temp-URL-Key (Optional) header string The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional) header string A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional) header string Extra transaction information. Use the X-Trans- Id-Extra request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. Object Storage appends the first 32 characters of the X-Trans-Id- Extra request header value to the transaction ID value in the generated X-Trans-Id response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the X -Trans-Id-Extra request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the X-Trans-Id-Extra request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use X-Trans-Id- Extra strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters

Name In Type Description
Date header string

The transaction date and time.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

X-Timestamp header integer The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
Content-Length header string If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type (Optional) header string Changes the MIME type for the object.
X-Trans-Id header string A unique transaction ID for this request. Your service provider might need this value if you report a problem.

Discoverability

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

GET
/info

List activated capabilities

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

Normal response codes: 200 Error response codes:

Request

Name In Type Description
swiftinfo_sig (Optional) query string A hash-based message authentication code (HMAC) that enables access to administrator-only information. To use this parameter, the swiftinfo_expires parameter is also required.
swiftinfo_expires (Optional) query integer Filters the response by the expiration date and time in UNIX Epoch time stamp format. For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.

Response Example

{
    "swift": {
        "version": "1.11.0"
    },
    "staticweb": {},
    "tempurl": {}
}
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.