Overview

The IBM Cloud Object Storage implementation of the S3 API supports the most commonly used subset of Amazon S3 API operations. A complete list of supported operations can be found in the API overview.

Common Headers

Common Request Headers

The following table describes supported common request headers. COS ignores any common headers not listed below if sent in a request, although some requests may support other headers as defined in this documentation. More information about creating the authorization header can be found in the “Authentication” section

Header Note
Authorization Required for all requests (AWS Signature Version 4).
Host Required for all requests.
x-amz-date Required for all requests. Can also be specified as Date.
x-amz-content-sha256 Required for uploading objects or any request with information in the body.
Content-Length Required for uploading objects, chunked encoding also supported.
Content-MD5 A 128-bit MD5 hash value of the request body being sent.
Expect 100-continue waits for the headers to be accepted before sending the body.

Common Response Headers

The following table describes common response headers.

Header Note
Content-Length The length of the request body in bytes.
Connection Indicates whether the connection is open or closed.
Date Timestamp of the request.
ETag MD5 hash value of the request.
Server Name of the responding server.
X-Clv-Request-Id Unique identifier generated per request.

Error Codes

Error Code Description HTTP Status Code
AccessDenied Access Denied 403 Forbidden
AccessDenied Access Denied - Server-Side Encryption with Customer-Provided Keys is not enabled for this vault. 403 Forbidden
BadDigest The Content-MD5 you specified did not match what we received. 400 Bad Request
BucketAlreadyExists The requested bucket name is not available. The bucket namespace is shared by all users of the system. Please select a different name and try again. 409 Conflict
BucketNotEmpty The bucket you tried to delete is not empty. 409 Conflict
CredentialsNotSupported This request does not support credentials. 400 Bad Request
EntityTooSmall Your proposed upload is smaller than the minimum allowed object size. 400 Bad Request
EntityTooLarge Your proposed upload exceeds the maximum allowed object size. 400 Bad Request
IncompleteBody You did not provide the number of bytes specified by the Content-Length HTTP header. 400 Bad Request
IncorrectNumberOfFilesInPostRequest POST requires exactly one file upload per request. 400 Bad Request
InlineDataTooLarge Inline data exceeds the maximum allowed size. 400 Bad Request
InternalError We encountered an internal error. Please try again. 500 Internal Server Error
InvalidAccessKeyId The AWS access key Id you provided does not exist in our records. 403 Forbidden
InvalidArgument Invalid Argument 400 Bad Request
InvalidArgument Requests specifying Server-Side Encryption with Customer-Provided Keys must be made over a secure connection. 400 Bad Request
InvalidArgument Requests specifying Server-Side Encryption with Customer-Provided Keys must provide an appropriate secret key. 400 Bad Request
InvalidArgument Requests specifying Server-Side Encryption with Customer-Provided Keys must provide the client calculated MD5 of the secret key. 400 Bad Request
InvalidArgument The MD5 hash of the secret key was improperly encoded. The MD5 hash must be Base64 encoded. 400 Bad Request
InvalidArgument The calculated MD5 hash of the key did not match the hash that was provided. 400 Bad Request
InvalidBucketName The specified bucket is not valid. 400 Bad Request
InvalidBucketState The request is not valid with the current state of the bucket. 409 Conflict
InvalidDigest The Content-MD5 you specified is not valid. 400 Bad Request
InvalidEncryptionAlgorithmError The Encryption request you specified is not valid. Supported value: AES256. 400 Bad Request
InvalidLocationConstraint The specified location constraint is not valid. For more information about regions, see How to Select a Region for Your Buckets. 400 Bad Request
InvalidObjectState The operation is not valid for the current state of the object. 403 Forbidden
InvalidPart One or more of the specified parts could not be found. The part might not have been uploaded, or the specified entity tag might not have matched the part’s entity tag. 400 Bad Request
InvalidPartOrder The list of parts was not in ascending order. Parts list must specified in order by part number. 400 Bad Request
InvalidRange The requested range cannot be satisfied. 416 Requested Range Not Satisfiable
InvalidRequest Please use AWS4-HMAC-SHA256. 400 Bad Request
InvalidRequest The object was stored using a form of Server-Side Encryption. The correct parameters must be provided to retrieve the object. 400 Bad Request
InvalidRequest The encryption parameters are not applicable to this object. 400 Bad Request
InvalidRequest The object was stored using a form of Server-Side Encryption. The correct parameters must be provided to retrieve the object. 400 Bad Request
InvalidSecurity The provided security credentials are not valid. 403 Forbidden
InvalidURI Couldn’t parse the specified URI. 400 Bad Request
KeyTooLong Your key is too long. 400 Bad Request
MalformedACLError The XML you provided was not well-formed or did not validate against our published schema. 400 Bad Request
MalformedPOSTRequest The body of your POST request is not well-formed multipart/form-data. 400 Bad Request
MalformedXML This happens when the user sends malformed xml (xml that doesn’t conform to the published xsd) for the configuration. The error message is, “The XML you provided was not well-formed or did not validate against our published schema.” 400 Bad Request
MaxMessageLengthExceeded Your request was too big. 400 Bad Request
MaxPostPreDataLengthExceededError Your POST request fields preceding the upload file were too large. 400 Bad Request
MetadataTooLarge Your metadata headers exceed the maximum allowed metadata size. 400 Bad Request
MethodNotAllowed The specified method is not allowed against this resource. 405 Method Not Allowed
MissingContentLength You must provide the Content-Length HTTP header. 411 Length Required
MissingRequestBodyError This happens when the user sends an empty xml document as a request. The error message is, “Request body is empty.” 400 Bad Request
NoSuchBucket The specified bucket does not exist. 404 Not Found
NoSuchKey The specified key does not exist. 404 Not Found
NoSuchUpload The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed. 404 Not Found
NotImplemented A header you provided implies functionality that is not implemented. 501 Not Implemented
OperationAborted A conflicting conditional operation is currently in progress against this resource. Try again. 409 Conflict
PreconditionFailed At least one of the preconditions you specified did not hold. 412 Precondition Failed
Redirect Temporary redirect. 307 Moved Temporarily
RequestIsNotMultiPartContent Bucket POST must be of the enclosure-type multipart/form-data. 400 Bad Request
RequestTimeout Your socket connection to the server was not read from or written to within the timeout period. 400 Bad Request
RequestTimeTooSkewed The difference between the request time and the server’s time is too large. 403 Forbidden
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your AWS secret access key and signing method. For more information, see REST Authentication and SOAP Authentication for details. 403 Forbidden
ServiceUnavailable Reduce your request rate. 503 Service Unavailable
SlowDown Reduce your request rate. 503 Slow Down
TemporaryRedirect You are being redirected to the bucket while DNS updates. 307 Moved Temporarily
TooManyBuckets You have attempted to create more buckets than allowed. 400 Bad Request
UnexpectedContent This request does not support content. 400 Bad Request
UnresolvableGrantByEmailAddress The email address you provided does not match any account on record. 400 Bad Request
UserKeyMustBeSpecified The bucket POST must contain the specified field name. If it is specified, check the order of the fields. 400 Bad Request
VaultQuotaExceeded The capacity used on the target vault has exceeded a hard quota 507 Insufficient Storage

Operations on the Account

List buckets belonging to an account

A GET issued to the endpoint root returns a list of buckets owned by the requesting account. This operation does not make use of operation specific headers, query parameters, or payload elements.

Syntax
GET https://{endpoint}/
Sample request
GET / HTTP/1.1
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
X-Amz-Date: 20160822T030815Z
Authorization: {authorization-string}
Sample response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>{access-key}</ID>
        <DisplayName>{access-key}</DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>bucket-27200-lwx4cfvcue</Name>
            <CreationDate>2016-08-18T14:21:36.593Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>bucket-27590-drqmydpfdv</Name>
            <CreationDate>2016-08-18T14:22:32.366Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>bucket-27852-290jtb0n2y</Name>
            <CreationDate>2016-08-18T14:23:03.141Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>bucket-28731-k0o1gde2rm</Name>
            <CreationDate>2016-08-18T14:25:09.599Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Operations on Buckets

Create a new bucket

A PUT issued to the endpoint root followed by a string will create a bucket using that string for a name. Bucket names must be unique, and storage instances are limited to 100 buckets. Bucket names are required to be DNS-compliant; names must be between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes. Bucket names must begin and end with a lowercase letter or number. Bucket names resembling IP addresses are not allowed, although dot characters (.) are permitted. This operation does not make use of operation specific headers or query parameters.

Syntax
PUT https://{endpoint}/{bucket-name} # path style
PUT https://{bucket-name}.{endpoint} # virtual host style

Optional payload elements

If an XML block specifying a LocationConstraint is provided it must correspond with a valid provisioning code (e.g. us-standard). If the request payload is left empty, the default provisioning code is used.

<CreateBucketConfiguration>
  <LocationConstraint>{provisioning-code}</LocationConstraint>
</CreateBucketConfiguration>
Sample request

This is an example of creating a new bucket called ‘images’.

PUT /images HTTP/1.1
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
X-Amz-Date: 20160821T052842Z
Authorization:{authorization-string}
Sample response
HTTP/1.1 200 OK
Date: Wed, 24 Aug 2016 17:45:25 GMT
X-Clv-Request-Id: dca204eb-72b5-4e2a-a142-808d2a5c2a87
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
x-amz-request-id: dca204eb-72b5-4e2a-a142-808d2a5c2a87
Content-Length: 0

Create a Vault bucket

To create a Vault bucket, send an XML block specifying a bucket configuration with a LocationConstraint of us-vault in the body of a PUT request to a bucket endpoint. Note that standard bucket naming rules apply.

Syntax
PUT https://{endpoint}/{bucket-name} # path style
PUT https://{bucket-name}.{endpoint} # virtual host style
<CreateBucketConfiguration>
  <LocationConstraint>us-vault</LocationConstraint>
</CreateBucketConfiguration>
Sample request

This is an example of creating a new bucket called ‘vault-images’.

PUT /vault-images HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170317T175217Z
x-amz-content-sha256: {hashed-request-body}
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 110
<CreateBucketConfiguration>
  <LocationConstraint>us-vault</LocationConstraint>
</CreateBucketConfiguration>
Sample response
HTTP/1.1 200 OK
Date: Fri, 17 Mar 2017 17:52:17 GMT
X-Clv-Request-Id: b6483b2c-24ae-488a-884c-db1a93b9a9a6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
Content-Length: 0

Create a Cold Vault bucket

To create a Vault bucket, send an XML block specifying a bucket configuration with a LocationConstraint of us-cold in the body of a PUT request to a bucket endpoint. Note that standard bucket naming rules apply.

Syntax
PUT https://{endpoint}/{bucket-name} # path style
PUT https://{bucket-name}.{endpoint} # virtual host style
<CreateBucketConfiguration>
  <LocationConstraint>us-cold</LocationConstraint>
</CreateBucketConfiguration>
Sample request

This is an example of creating a new bucket called ‘cold-vault-images’.

PUT /cold-vault-images HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170317T175217Z
x-amz-content-sha256: {hashed-request-body}
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 110
<CreateBucketConfiguration>
  <LocationConstraint>us-cold</LocationConstraint>
</CreateBucketConfiguration>
Sample response
HTTP/1.1 200 OK
Date: Fri, 17 Mar 2017 17:52:17 GMT
X-Clv-Request-Id: b6483b2c-24ae-488a-884c-db1a93b9a9a6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
Content-Length: 0

Create a Flex bucket

To create a Flex bucket, send an XML block specifying a bucket configuration with a LocationConstraint of us-flex in the body of a PUT request to a bucket endpoint. Note that standard bucket naming rules apply.

Syntax
PUT https://{endpoint}/{bucket-name} # path style
PUT https://{bucket-name}.{endpoint} # virtual host style
<CreateBucketConfiguration>
  <LocationConstraint>us-flex</LocationConstraint>
</CreateBucketConfiguration>
Sample request

This is an example of creating a new bucket called ‘flex-images’.

PUT /flex-images HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170317T175217Z
x-amz-content-sha256: {hashed-request-body}
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 110
<CreateBucketConfiguration>
  <LocationConstraint>us-flex</LocationConstraint>
</CreateBucketConfiguration>
Sample response
HTTP/1.1 200 OK
Date: Fri, 17 Mar 2017 17:52:17 GMT
X-Clv-Request-Id: b6483b2c-24ae-488a-884c-db1a93b9a9a6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
Content-Length: 0

Retrieve a bucket’s headers

A HEAD issued to a bucket resource will return the headers for that bucket. This operation does not make use of operation specific headers, query parameters, or payload elements.

Syntax
HEAD https://{endpoint}/{bucket-name} # path style
HEAD https://{bucket-name}.{endpoint} # virtual host style
Sample request

This is an example of fetching the headers for the ‘images’ bucket.

HEAD /images HTTP/1.1
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
X-Amz-Date: 20160821T052842Z
Authorization:{authorization-string}
Sample response
HTTP/1.1 200 OK
Date: Wed, 24 Aug 2016 17:46:35 GMT
X-Clv-Request-Id: 0c2832e3-3c51-4ea6-96a3-cd8482aca08a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
x-amz-request-id: 0c2832e3-3c51-4ea6-96a3-cd8482aca08a
Content-Length: 0

List objects in a given bucket

A GET request addressed to a bucket returns a list of objects, limited to 1,000 at a time and returned in non-lexographical order. The StorageClass value that is returned in the response is a default value as storage class operations are not implemented in COS. This operation does not make use of operation specific headers or payload elements.

Syntax
GET https://{endpoint}/{bucket-name} # path style
GET https://{bucket-name}.{endpoint} # virtual host style
Optional query parameters
Name Type Description
prefix string Constrains response to object names beginning with prefix.
delimiter string Groups objects between the prefix and the delimiter.
encoding-type string If unicode characters that are not supported by XML are used in an object name, this parameter can be set to url to properly encode the response.
max-keys string Restricts the number of objects to display in the response. Default and maximum is 1,000.
marker string Specifies the object from where the listing should begin, in UTF-8 binary order.
Sample request

This request lists the objects inside the “apiary” bucket.

GET /apiary HTTP/1.1
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
X-Amz-Date: 20160822T225156Z
Authorization: {authorization-string}
Sample response
HTTP/1.1 200 OK
Date: Wed, 24 Aug 2016 17:36:24 GMT
X-Clv-Request-Id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Content-Type: application/xml
Content-Length: 909
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter/>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>drone-bee</Key>
    <LastModified>2016-08-25T17:38:38.549Z</LastModified>
    <ETag>"0cbc6611f5540bd0809a388dc95a615b"</ETag>
    <Size>4</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>worker-bee</Key>
    <LastModified>2016-08-25T17:46:53.288Z</LastModified>
    <ETag>"d34d8aada2996fc42e6948b926513907"</ETag>
    <Size>467</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Delete a bucket

A DELETE issued to an empty bucket deletes the bucket. After deleting a bucket the name will be held in reserve by the system for 10 minutes, after which it will be released for re-use. Only empty buckets can be deleted. This operation does not make use of operation specific headers, query parameters, or payload elements.

Syntax
DELETE https://{endpoint}/{bucket-name} # path style
DELETE https://{bucket-name}.{endpoint} # virtual host style
Sample request
DELETE /images HTTP/1.1
Host: s3-api.us-geo.objectstorage.softlayer.net
x-amz-date: 20160822T064812Z
Authorization: {authorization-string}

The server responds with 204 No Content.

If a non-empty bucket is requested for deletion, the server responds with 409 Conflict.

Sample request
DELETE /apiary HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T174049Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
<Error>
  <Code>BucketNotEmpty</Code>
  <Message>The bucket you tried to delete is not empty.</Message>
  <Resource>/apiary/</Resource>
  <RequestId>9d2bbc00-2827-4210-b40a-8107863f4386</RequestId>
  <httpStatusCode>409</httpStatusCode>
</Error>

Create an access control list for a bucket

A PUT issued to a bucket with the necessary query parameter creates or replaces an access control list (ACL) for that bucket. Access control lists allow for granting different sets of permissions to different storage accounts using the account’s ID, or by using a pre-made ACL.

ACLs can use pre-made permissions sets (or ‘canned ACLs’) or be customized in the body of the request. Pre-made ACLs are specified using the x-amz-acl header and custom ACLs are specified using XML in the request payload. Only one method (header or payload) can be used in a single request.

This operation does not make use of additional operation specific query parameters.

ACL grantees must be other COS storage instances, and their UUID can be found along with credentials in the web portal.

The assigned permissions behave as follows:

Permission When granted on a bucket When granted on an object
READ Allows grantee to list and read all objects in bucket Allows grantee to read object data and metadata
WRITE Allows grantee to create, overwrite and delete any object in bucket. Cannot be granted independently from READ permission. N/A
READ_ACP This permission does not exist for buckets; default setting is FULL_CONTROL Allows grantee to read object ACL
WRITE_ACP Default setting is FULL_CONTROL Allows grantee to write ACL for applicable object
FULL_CONTROL Allows grantee READ, WRITE, READ_ACP and WRITE_ACP permissions on bucket Allows grantee READ, READ_ACP and WRITE_ACP permissions on object

Note: The READ_ACP, WRITE_ACP, and FULL_CONTROL permissions are implied by the bucket “own” permission. When any of these permissions are assigned to a grantee in a bucket ACL, that grantee will be granted the bucket “own” permission.

The following canned ACLs are supported by IBM COS. Values not listed below are not supported.

Canned ACL Applies to Notes
private Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
public-read Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
public-read-write Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
authenticated-read Bucket and object Supported when set on an object only. Not supported as a bucket ACL.
Syntax
PUT https://{endpoint}/{bucket-name}?acl= # path style
PUT https://{bucket-name}.{endpoint}?acl= # virtual host style
Sample request Basic pre-made ACL

This is an example of specifying a pre-made ACL to allow for public-read access to the “apiary” bucket. This allows any storage account to view the bucket’s contents and ACL details.

PUT /apiary?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
x-amz-acl: public-read
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Tue, 4 Oct 2016 19:03:55 GMT
X-Clv-Request-Id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Content-Length: 0
Sample request Custom ACL

This is an example of specifying a custom ACL to allow for another user using their username to view the ACL for the “apiary” bucket, but not to list objects stored inside the bucket. A third account is given full access to the same bucket as another element of the same ACL. All authenticated users of the system can list objects in the bucket.

PUT /apiary?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: s3-api.us-geo.objectstorage.softlayer.net
<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>OwnerDisplayName</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{first-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee1DisplayName</DisplayName>
      </Grantee>
      <Permission>READ_ACP</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{second-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee2DisplayName</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>
Sample response
HTTP/1.1 200 OK
Date: Tue, 4 Oct 2016 19:03:55 GMT
X-Clv-Request-Id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 73d3cd4a-ff1d-4ac9-b9bb-43529b11356a

Retrieve the access control list for a bucket

A GET issued to a bucket with the proper parameters retrieves the ACL for a bucket. This operation does not make use of operation specific headers, additional query parameters, or payload elements.

Syntax
GET https://{endpoint}/{bucket-name}?acl= # path style
GET https://{bucket-name}.{endpoint}?acl= # virtual host style
Sample request

This is an example of retrieving a bucket ACL.

GET /apiary?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Wed, 5 Oct 2016 14:14:34 GMT
X-Clv-Request-Id: eb57e60e-d84e-4237-b18a-be9c2bb0deb8
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: eb57e60e-d84e-4237-b18a-be9c2bb0deb8
Content-Type: application/xml
Content-Length: 550
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>{owner-storage-account-uuid}</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{owner-storage-account-uuid}</ID>
        <DisplayName>{owner-storage-account-uuid}</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

List canceled/incomplete multipart uploads for a bucket

A GET issued to a bucket with the proper parameters retrieves information about any canceled or incomplete multipart uploads for a bucket. This operation does not make use of operation specific headers, additional query parameters, or payload elements.

Syntax
GET https://{endpoint}/{bucket-name}?uploads= # path style
GET https://{bucket-name}.{endpoint}?uploads= # virtual host style

Parameters

Name Type Description
prefix string Constrains response to object names beginning with {prefix}.
delimiter string Groups objects between the prefix and the delimiter.
encoding-type string If unicode characters that are not supported by XML are used in an object name, this parameter can be set to url to properly encode the response.
max-uploads integer Restricts the number of objects to display in the response. Default and maximum is 1,000.
key-marker string Specifies from where the listing should begin.
upload-id-marker string Ignored if key-marker is not specified, otherwise sets a point at which to begin listing parts above upload-id-marker.
Sample request

This is an example of retrieving all current canceled and incomplete multipart uploads.

GET /apiary?uploads= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response (no multipart uploads in progress)
HTTP/1.1 200 OK
Date: Wed, 5 Oct 2016 15:22:27 GMT
X-Clv-Request-Id: 9fa96daa-9f37-42ee-ab79-0bcda049c671
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 9fa96daa-9f37-42ee-ab79-0bcda049c671
Content-Type: application/xml
Content-Length: 374
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>apiary</Bucket>
  <KeyMarker/>
  <UploadIdMarker/>
  <NextKeyMarker>multipart-object-123</NextKeyMarker>
  <NextUploadIdMarker>0000015a-df89-51d0-2790-dee1ac994053</NextUploadIdMarker>
  <MaxUploads>1000</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <Upload>
    <Key>file</Key>
    <UploadId>0000015a-d92a-bc4a-c312-8c1c2a0e89db</UploadId>
    <Initiator>
      <ID>d4d11b981e6e489486a945d640d41c4d</ID>
      <DisplayName>d4d11b981e6e489486a945d640d41c4d</DisplayName>
    </Initiator>
    <Owner>
      <ID>d4d11b981e6e489486a945d640d41c4d</ID>
      <DisplayName>d4d11b981e6e489486a945d640d41c4d</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2017-03-16T22:09:01.002Z</Initiated>
  </Upload>
  <Upload>
    <Key>multipart-object-123</Key>
    <UploadId>0000015a-df89-51d0-2790-dee1ac994053</UploadId>
    <Initiator>
      <ID>d4d11b981e6e489486a945d640d41c4d</ID>
      <DisplayName>d4d11b981e6e489486a945d640d41c4d</DisplayName>
    </Initiator>
    <Owner>
      <ID>d4d11b981e6e489486a945d640d41c4d</ID>
      <DisplayName>d4d11b981e6e489486a945d640d41c4d</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2017-03-18T03:50:02.960Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>

List any cross-origin resource sharing configuration for a bucket

A GET issued to a bucket with the proper parameters retrieves information about cross-origin resource sharing (CORS) configuration for a bucket. This operation does not make use of operation specific headers, additional query parameters, or payload elements.

Syntax
GET https://{endpoint}/{bucket-name}?cors= # path style
GET https://{bucket-name}.{endpoint}?cors= # virtual host style
Sample request

This is an example of listing a CORS configuration on the “apiary” bucket.

GET /apiary?cors= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response No CORS configuration set
HTTP/1.1 200 OK
Date: Wed, 5 Oct 2016 15:20:30 GMT
X-Clv-Request-Id: 0b69bce1-8420-4f93-a04a-35d7542799e6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 0b69bce1-8420-4f93-a04a-35d7542799e6
Content-Type: application/xml
Content-Length: 123
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"/>

Create a cross-origin resource sharing configuration for a bucket

A PUT issued to a bucket with the proper parameters creates or replaces a cross-origin resource sharing (CORS) configuration for a bucket. Note that in addition to a SHA256 hash of the body, a Content-MD5 header is required as well. This operation does not make use of operation specific headers or additional query parameters.

Syntax
PUT https://{endpoint}/{bucket-name}?cors= # path style
PUT https://{bucket-name}.{endpoint}?cors= # virtual host style

Optional payload elements

In the XML block defining the key CORS elements (AllowedOrigin and AllowedMethod) there are two optional elements that can be optionally specified.

Element Description
MaxAgeSeconds Time in seconds that the browser will cache the response to the pre-flight OPTIONS request for the specified resource.
ExposeHeader Defines specific headers that will be exposed to external applications.
Sample request

This is an example of adding a CORS configuration that allows requests from www.ibm.com to issue GET, PUT, and POST requests to the bucket.

GET /apiary?cors= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
x-amz-content-sha256: 2938f51643d63c864fdbea618fe71b13579570a86f39da2837c922bae68d72df
Content-MD5: GQmpTNpruOyK6YrxHnpj7g==
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 237
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>http:www.ibm.com</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
  </CORSRule>
</CORSConfiguration>
Sample response
HTTP/1.1 200 OK
Date: Wed, 5 Oct 2016 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.129
X-Clv-S3-Version: 2.5
x-amz-request-id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Content-Length: 0

Delete any cross-origin resource sharing configuration for a bucket

A DELETE issued to a bucket with the proper parameters creates or replaces a cross-origin resource sharing (CORS) configuration for a bucket.

Syntax
DELETE https://{endpoint}/{bucket-name}?cors= # path style
DELETE https://{bucket-name}.{endpoint}?cors= # virtual host style
Sample request

This is an example of deleting a CORS configuration for a bucket.

GET /apiary?cors= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161011T190354Z
Host: s3-api.us-geo.objectstorage.softlayer.net

The server responds with 204 No Content.


Operations on Objects

Upload an object

A PUT given a path to an object uploads the request body as an object. A SHA256 hash of the object is a required header. All objects are limited to 5TB in size. This operation does not make use of operation specific query parameters, or payload elements.

Syntax
PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style
Specific headers for SSE-C

The following headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C). Any request using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string.

Header Type Description
x-amz-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request
PUT /example-bucket/queen-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T183001Z
x-amz-content-sha256: 309721641329cf441f3fa16ef996cf24a2505f91be3e752ac9411688e3435429
Content-Type: text/plain; charset=utf-8
Host: s3-api.us-geo.objectstorage.softlayer.net

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly'. After a short while the 'queen' is
 the mother of nearly every bee in the hive, and the colony will fight
 fiercely to protect her.

Sample response
HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
Content-Length: 0
Sample request using SSE-C
PUT /example-bucket/queen-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T183001Z
x-amz-content-sha256: 309721641329cf441f3fa16ef996cf24a2505f91be3e752ac9411688e3435429
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: MjRCRTJCQTNDQjdFOTkyMzY0NjZEN0NBMDhGQTBGRUQwNzFBMjEwMkQyNjU4MjNEOEMyODU5MkQxQ0ZEMkQ1OQ==
x-amz-server-side-encryption-customer-key-MD5: HBbrEt+ZH5iIfDNeBju03w==
Content-Type: text/plain; charset=utf-8
Host: s3-api.us-geo.objectstorage.softlayer.net

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly'. After a short while the 'queen' is
 the mother of nearly every bee in the hive, and the colony will fight
 fiercely to protect her.

Sample response
HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: HBbrEt+ZH5iIfDNeBju03w==
Content-Length: 0

Get an object’s headers

A HEAD given a path to an object retrieves that object’s headers. This operation does not make use of operation specific query parameters or payload elements.

Syntax
HEAD https://{endpoint}/{bucket-name}/{object-name} # path style
HEAD https://{bucket-name}.{endpoint}/{object-name} # virtual host style

Optional headers

Header Type Description
range string Returns the bytes of an object within the specified range.
x-amz-copy-source-if-match string (ETag) Return the metadata if the specified ETag matches the source object.
x-amz-copy-source-if-none-match string (ETag) Return the metadata if the specified ETag is different from the source object.
x-amz-copy-source-if-unmodified-since string (timestamp) Return the metadata if the the source object has not been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).
x-amz-copy-source-if-modified-since string (timestamp) Return the metadata if the source object has been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).

Specific headers for SSE-C

The following headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C). Anyrequest using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string.

Header Type Description
x-amz-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request
HEAD /example-bucket/soldier-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T183244Z
Host: s3-api.us-geo.objectstorage.softlayer.net

Sample response
HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:32:44 GMT
X-Clv-Request-Id: da214d69-1999-4461-a130-81ba33c484a6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: da214d69-1999-4461-a130-81ba33c484a6
ETag: "37d4c94839ee181a2224d6242176c4b5"
Content-Type: text/plain; charset=UTF-8
Last-Modified: Thu, 25 Aug 2016 17:49:06 GMT
Content-Length: 11

Download an object

A GET given a path to an object downloads the object. This operation does not make use of operation specific query parameters or payload elements.

Syntax
GET https://{endpoint}/{bucket-name}/{object-name} # path style
GET https://{bucket-name}.{endpoint}/{object-name} # virtual host style

Optional headers

Header Type Description
range string Returns the bytes of an object within the specified range.
x-amz-copy-source-if-match string (ETag) Return the object if the specified ETag matches the source object.
x-amz-copy-source-if-none-match string (ETag) Return the object if the specified ETag is different from the source object.
x-amz-copy-source-if-unmodified-since string (timestamp) Return the object if the the source object has not been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).
x-amz-copy-source-if-modified-since string (timestamp) Return the object if the source object has been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).

Specific headers for SSE-C

The following headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C). Any request using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string.

Header Type Description
x-amz-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request
GET /example-bucket/worker-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T183244Z
Host: s3-api.us-geo.objectstorage.softlayer.net

Sample response
HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:34:25 GMT
X-Clv-Request-Id: 116dcd6b-215d-4a81-bd30-30291fa38f93
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
ETag: "d34d8aada2996fc42e6948b926513907"
Content-Type: text/plain; charset=UTF-8
Last-Modified: Thu, 25 Aug 2016 17:46:53 GMT
Content-Length: 467

 Female bees that are not fortunate enough to be selected to be the 'queen'
 while they were still larvae become known as 'worker' bees. These bees lack
 the ability to reproduce and instead ensure that the hive functions smoothly,
 acting almost as a single organism in fulfilling their purpose.

Delete an object

A DELETE given a path to an object deletes an object. This operation does not make use of operation specific query parameters, headers, or payload elements.

Syntax
DELETE https://{endpoint}/{bucket-name}/{object-name} # path style
DELETE https://{bucket-name}.{endpoint}/{object-name} # virtual host style
Sample request
DELETE /example-bucket/soldier-bee HTTP/1.1
Authorization: {authorization-string}
Host: s3-api.us-geo.objectstorage.softlayer.net

Sample response
HTTP/1.1 204 No Content
Date: Thu, 25 Aug 2016 17:44:57 GMT
X-Clv-Request-Id: 8ff4dc32-a6f0-447f-86cf-427b564d5855
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5

Deleting multiple objects

A POST given a path to an bucket and proper parameters will delete a specified set of objects. This requires a Content-MD5 header in addition to the x-amz-content-sha256 header. This operation does not make use of operation specific query parameters, headers, or payload elements.

Syntax
POST https://{endpoint}/{bucket-name}/{object-name}?delete= # path style
POST https://{bucket-name}.{endpoint}/{object-name}?delete= # virtual host style
Sample request
POST /example?delete= HTTP/1.1
Authorization: {authorization-string}
Host: s3-api.us-geo.objectstorage.softlayer.net
x-amz-date: 20161205T231624Z
x-amz-content-sha256: 3ade096cd9471017539ede10c4d8aa05a1ecd015a16f4f090e9fcee92a816cf4
Content-MD5: zhi+TmIAhD2U3GfoYayyTQ==
Content-Type: text/plain; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<Delete>
    <Object>
         <Key>surplus-bee</Key>
    </Object>
    <Object>
         <Key>unnecessary-bee</Key>
    </Object>
</Delete>
Sample response
HTTP/1.1 200 OK
Date: Wed, 30 Nov 2016 18:54:53 GMT
X-Clv-Request-Id: a6232735-c3b7-4c13-a7b2-cd40c4728d51
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: a6232735-c3b7-4c13-a7b2-cd40c4728d51
Content-Type: application/xml
Content-Length: 207
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Deleted>
         <Key>surplus-bee</Key>
    </Deleted>
    <Deleted>
         <Key>unnecessary-bee</Key>
    </Deleted>
</DeleteResult>

Copy an object

A PUT given a path to a new object creates a new copy of another object specified by the x-amz-copy-source header. Unless otherwise altered the metadata remains the same, although any ACL is reset to private for the account creating the copy. This operation does not make use of operation specific query parameters or payload elements.

Syntax
PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

Optional headers

Header Type Description
x-amz-metadata-directive string (COPY or REPLACE) REPLACE will overwrite original metadata with new metadata that is provided.
x-amz-copy-source-if-match string (ETag) Creates a copy if the specified ETag matches the source object.
x-amz-copy-source-if-none-match string (ETag) Creates a copy if the specified ETag is different from the source object.
x-amz-copy-source-if-unmodified-since string (timestamp) Creates a copy if the the source object has not been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).
x-amz-copy-source-if-modified-since string (timestamp) Creates a copy if the source object has been modified since the specified date. Date must be a valid HTTP date (e.g. Wed, 30 Nov 2016 20:21:38 GMT).

Specific headers for SSE-C

The following headers are available for objects being copied into buckets that have Server Side Encryption with Customer-Provided Keys (SSE-C). Any PUT request using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string.

The specific SSE-C headers used to initially upload objects are required if the copy operation will encrypt the copy of the data at the target destination. If the original/source object was encrypted using SSE-C, the spefic headers used for copying objects will need to be present to decrypt the object source. Copies of objects do not need to be encrypted with the same key.

Header Type Description
x-amz-copy-source-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-copy-source-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-copy-source-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-copy-source-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-copy-source-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request

This basic example takes the bee object from the garden bucket, and creates a copy in the example bucket with the new key wild-bee.

PUT /example-bucket/wild-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161130T195251Z
x-amz-copy-source: /garden/bee
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Wed, 30 Nov 2016 19:52:52 GMT
X-Clv-Request-Id: 72992a90-8f86-433f-b1a4-7b1b33714bed
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 72992a90-8f86-433f-b1a4-7b1b33714bed
ETag: "853aab195ce770b0dfb294a4e9467e62"
Content-Type: application/xml
Content-Length: 240
<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LastModified>2016-11-30T19:52:53.125Z</LastModified>
  <ETag>"853aab195ce770b0dfb294a4e9467e62"</ETag>
</CopyObjectResult>

Retrieve an object’s ACL

A GET given a path to an object given the parameter ?acl= retrieves the access control list for the object. This operation does not make use of operation specific headers, additional query parameters or payload elements.

Syntax
GET https://{endpoint}/{bucket-name}/{object-name}?acl= # path style
GET https://{bucket-name}.{endpoint}/{object-name}?acl= # virtual host style
Sample request
GET /example-bucket/queen-bee?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T155945Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 15:59:46 GMT
X-Clv-Request-Id: 78541562-29bf-4800-9eb3-0c360f0a037a
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 78541562-29bf-4800-9eb3-0c360f0a037a
Content-Type: application/xml
Content-Length: 550
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>{owner-storage-account-uuid}</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{owner-storage-account-uuid}</ID>
        <DisplayName>{owner-storage-account-uuid}</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Create an ACL for an object

A PUT issued to an object with the proper parameters creates an access control list (ACL) for that object. Access control lists allow for granting different sets of permissions to different storage accounts using the account’s ID, or by using a pre-made ACL.

The assigned permissions behave as follows:

Permission When granted on a bucket When granted on an object
READ Allows grantee to list and read all objects in bucket Allows grantee to read object data and metadata
WRITE Allows grantee to create, overwrite and delete any object in bucket. Cannot be granted independently from READ permission. N/A
READ_ACP This permission does not exist for buckets; default setting is FULL_CONTROL Allows grantee to read object ACL
WRITE_ACP Default setting is FULL_CONTROL Allows grantee to write ACL for applicable object
FULL_CONTROL Allows grantee READ, WRITE, READ_ACP and WRITE_ACP permissions on bucket Allows grantee READ, READ_ACP and WRITE_ACP permissions on object

The following canned ACLs are supported by IBM COS. Values not listed below are not supported.

Canned ACL Applies to Notes
private Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
public-read Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
public-read-write Bucket and object When set on a bucket, the requestor is interpreted as the bucket owner.
Syntax
PUT https://{endpoint}/{bucket-name}/{object-name}?acl= # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?acl= # virtual host style
Sample request (canned ACL)
PUT /example-bucket/queen-bee?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T162842Z
x-amz-acl: public-read
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:28:42 GMT
X-Clv-Request-Id: b8dea44f-af20-466d-83ec-2a8563f1617b
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: b8dea44f-af20-466d-83ec-2a8563f1617b
Content-Length: 0
Sample request (canned ACL in header)

It is also possible to assign a canned ACL directly when uploading an object by passing the x-amz-acl header and a canned ACL value. This example makes the queen-bee object publicly and anonymously accessible.

PUT /example-bucket/queen-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T162842Z
x-amz-acl: public-read
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:28:42 GMT
X-Clv-Request-Id: b8dea44f-af20-466d-83ec-2a8563f1617b
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: b8dea44f-af20-466d-83ec-2a8563f1617b
Content-Length: 0
Sample request (custom ACL)

This is an example of specifying a custom ACL to allow for another account to view the ACL for the “queen-bee” object, but not to access object itself. Additionally, a third account is given full access to the same object as another element of the same ACL.

PUT /example-bucket/queen-bee?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T163315Z
Content-Type: text/plain
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 564
<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>OwnerDisplayName</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{first-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee1DisplayName</DisplayName>
      </Grantee>
      <Permission>READ_ACP</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{second-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee2DisplayName</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>
Sample response
HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 17:11:51 GMT
X-Clv-Request-Id: ef02ea42-6fa6-4cc4-bec4-c59bc3fcc9f7
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: ef02ea42-6fa6-4cc4-bec4-c59bc3fcc9f7
Content-Length: 0

Check an object’s CORS configuration

An OPTIONS given a path to an object along with an origin and request type checks to see if that object is accessible from that origin using that request type. Unlike all other requests, an OPTIONS request does not require the authorization or x-amx-date headers.

Syntax
OPTIONS https://{endpoint}/{bucket-name}/{object-name} # path style
OPTIONS https://{bucket-name}.{endpoint}/{object-name} # virtual host style
Sample request
OPTIONS /example-bucket/queen-bee HTTP/1.1
Access-Control-Request-Method: PUT
Origin: http://ibm.com
Host: s3-api.us-geo.objectstorage.softlayer.net

Sample response
HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:23:14 GMT
X-Clv-Request-Id: 9a2ae3e1-76dd-4eec-a8f2-1a7f60f63483
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 9a2ae3e1-76dd-4eec-a8f2-1a7f60f63483
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Credentials: true
Vary: Origin, Access-Control-Request-Headers, Access-Control-Allow-Methods
Content-Length: 0


Uploading objects in multiple parts

When working with larger objects, multipart upload operations are recommended to write objects into IBM COS. An upload of a single object can be performed as a set of parts and these parts can be uploaded independently in any order and in parallel. Upon upload completion, IBM COS then presents all parts as a single object. This provides many benefits: network interruptions do not cause large uploads to fail, uploads can be paused and restarted over time, and objects can be uploaded as they are being created.

Multipart uploads are only available for objects larger than 5MB. For objects smaller than 50GB, 500 parts sized 20MB to 100MB is recommended for optimum performance. For larger objects, part size can be increased without significant performance impact. Multipart uploads are limited to no more than 10,000 parts of 5GB each and a maximum object size of 5TB.

Due to the additional complexity involved, it is recommended that developers make use of S3 API libraries that provide multipart upload support.

Incomplete multipart uploads do persist until the object is deleted or the multipart upload is aborted with AbortIncompleteMultipartUpload. If an incomplete multipart upload is not aborted, the partial upload continues to use resources. Interfaces should be designed with this point in mind, and clean up incomplete multipart uploads.

There are three phases to uploading an object in multiple parts:

  1. The upload is initiated and an UploadId is created.
  2. Individual parts are uploaded specifying their sequential part numbers and the UploadId for the object.
  3. When all parts are finished uploading, the upload is completed by sending a request with the UploadId and an XML block that lists each part number and it’s respective Etag value.

Initiate a multipart upload

A POST issued to an object with the query parameter upload creates a new UploadId value, which is then be referenced by each part of the object being uploaded.

Syntax
POST https://{endpoint}/{bucket-name}/{object-name}?uploads= # path style
POST https://{bucket-name}.{endpoint}/{object-name}?uploads= # virtual host style

Specific headers for SSE-C

The following headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C). Any request using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string. These headers must be identical to those provided for each part of the multipart upload.

Header Type Description
x-amz-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request
POST /some-bucket/multipart-object-123?uploads= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170303T203411Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 200 OK
Date: Fri, 03 Mar 2017 20:34:12 GMT
X-Clv-Request-Id: 258fdd5a-f9be-40f0-990f-5f4225e0c8e5
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
Content-Type: application/xml
Content-Length: 276
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>some-bucket</Bucket>
  <Key>multipart-object-123</Key>
  <UploadId>0000015a-95e1-4326-654e-a1b57887784f</UploadId>
</InitiateMultipartUploadResult>

Upload a part

A PUT request issued to an object with query parameters partNumber and uploadId will upload one part of an object. The parts may be uploaded serially or in parallel, but must be numbered in order.

Syntax
PUT https://{endpoint}/{bucket-name}/{object-name}?partNumber={sequential-integer}&uploadId={uploadId}= # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?partNumber={sequential-integer}&uploadId={uploadId}= # virtual host style

Specific headers for SSE-C

The following headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C). Any request using SSE-C headers must be sent using SSL. Note that ETag values in response headers are not the MD5 hash of the object, but a randomly generated 32-byte hexadecimal string. These headers must be identical to those provided when the multipart operation was initiated.

Header Type Description
x-amz-server-side-encryption-customer-algorithm string This header is used to specify the algorithm and key size to use with the encryption key stored in x-amz-server-side-encryption-customer-key header. This value must be set to the string AES256.
x-amz-server-side-encryption-customer-key string This header is used to transport the base 64 encoded byte string representation of the AES 256 key used in the server side encryption process.
x-amz-server-side-encryption-customer-key-MD5 string This header is used to transport the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. The object store will use this value to validate the key passes in the x-amz-server-side-encryption-customer-key has not been corrupted during transport and encoding process. The digest must be calculated on the key BEFORE the key is base 64 encoded.
Sample request
PUT /some-bucket/multipart-object-123?partNumber=1&uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170318T035641Z
Content-Type: application/pdf
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 13374550
Sample response
HTTP/1.1 200 OK
Date: Sat, 18 Mar 2017 03:56:41 GMT
X-Clv-Request-Id: 17ba921d-1c27-4f31-8396-2e6588be5c6d
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
ETag: "7417ca8d45a71b692168f0419c17fe2f"
Content-Length: 0

Complete a multipart upload

A POST request issued to an object with query parameter uploadId and the appropriate XML block in the body will complete a multipart upload.

Syntax
POST https://{endpoint}/{bucket-name}/{object-name}?uploadId={uploadId}= # path style
POST https://{bucket-name}.{endpoint}/{object-name}?uploadId={uploadId}= # virtual host style
<CompleteMultipartUpload>
  <Part>
    <PartNumber>{sequential part number}</PartNumber>
    <ETag>{ETag value from part upload response header}</ETag>
  </Part>
</CompleteMultipartUpload>
Sample request
POST /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170318T035641Z
Content-Type: text/plain; charset=utf-8
Host: s3-api.us-geo.objectstorage.softlayer.net
Content-Length: 257
<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"7417ca8d45a71b692168f0419c17fe2f"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"7417ca8d45a71b692168f0419c17fe2f"</ETag>
  </Part>
</CompleteMultipartUpload>
Sample response
HTTP/1.1 200 OK
Date: Fri, 03 Mar 2017 19:18:44 GMT
X-Clv-Request-Id: c8be10e7-94c4-4c03-9960-6f242b42424d
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
ETag: "765ba3df36cf24e49f67fc6f689dfc6e-2"
Content-Type: application/xml
Content-Length: 364
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Location>http://s3-api.us-geo.objectstorage.softlayer.net/example-bucket/multipart-object-123</Location>
  <Bucket>some-bucket</Bucket>
  <Key>multipart-object-123</Key>
  <ETag>"765ba3df36cf24e49f67fc6f689dfc6e-2"</ETag>
</CompleteMultipartUploadResult>

Abort incomplete multipart uploads

A DELETE request issued to an object with query parameter uploadId will delete all unfinished parts of a multipart upload.

Syntax
DELETE https://{endpoint}/{bucket-name}/{object-name}?uploadId={uploadId}= # path style
DELETE https://{bucket-name}.{endpoint}/{object-name}?uploadId={uploadId}= # virtual host style
Sample request
DELETE /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20170318T035641Z
Host: s3-api.us-geo.objectstorage.softlayer.net
Sample response
HTTP/1.1 204 No Content
Date: Thu, 16 Mar 2017 22:07:48 GMT
X-Clv-Request-Id: 06d67542-6a3f-4616-be25-fc4dbdf242ad
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5