Bucket operations

The modern capabilities of IBM Cloud® Object Storage are conveniently available through a RESTful API. Operations and methods that are used to interact with buckets (where objects are stored) are documented here.

For more information about the permissions and access, see Bucket permissions.

A note about Access/Secret Key (HMAC) authentication

When authenticating to your instance of IBM Cloud® Object Storage by using HMAC credentials, you need the information that is represented in Table 1 when constructing an HMAC signature.

HMAC signature components
Key	Value	Example
{access_key}	Access key that is assigned to your Service Credential	`cf4965cebe074720a4929759f57e1214`
{date}	The formatted date of your request (`yyyymmdd`)	`20180613`
{region}	The location code for your endpoint	`us-standard`
{signature}	The hash that is created by using the secret key, location, and date	`ffe2b6e18f9dcc41f593f4dbb39882a6bb4d26a73a04326e62a8d344e07c1a3e`
{timestamp}	The formatted date and time of your request	`20180614T001804Z`

List buckets

A GET request that is sent to the endpoint root returns a list of buckets that are associated with the specified service instance. For more information about endpoints, see Endpoints and storage locations.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Headers
Header	Type	Required?	Description
`ibm-service-instance-id`	String	Yes	List buckets that were created in this service instance.

Query parameters
Query Parameter	Value	Required?	Description
`extended`	None	No	Provides `LocationConstraint` and `CreationTemplateId` metadata in the listing.

Syntax

GET https://{endpoint}/

Example request

GET / HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-service-instance-id: {ibm-service-instance-id}

Example request

GET / HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>{account-id}</ID>
        <DisplayName>{account-id}</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>

Getting an extended listing

Syntax

GET https://{endpoint}/?extended

Example request

GET /?extended HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-service-instance-id: {ibm-service-instance-id}

Example request

GET /?extended HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>{account-id}</ID>
        <DisplayName>{account-id}</DisplayName>
    </Owner>
    <IsTruncated>false</IsTruncated>
    <MaxKeys>1000</MaxKeys>
    <Prefix/>
    <Marker/>
    <Buckets>
        <Bucket>
            <Name>bucket-27200-lwx4cfvcue</Name>
            <CreationDate>2016-08-18T14:21:36.593Z</CreationDate>
            <LocationConstraint>us-south-standard</LocationConstraint>
        </Bucket>
        <Bucket>
            <Name>bucket-27590-drqmydpfdv</Name>
            <CreationDate>2016-08-18T14:22:32.366Z</CreationDate>
            <LocationConstraint>us-standard</LocationConstraint>
        </Bucket>
        <Bucket>
            <Name>bucket-27852-290jtb0n2y</Name>
            <CreationDate>2016-08-18T14:23:03.141Z</CreationDate>
            <LocationConstraint>eu-standard</LocationConstraint>
        </Bucket>
        <Bucket>
            <Name>bucket-28731-k0o1gde2rm</Name>
            <CreationDate>2016-08-18T14:25:09.599Z</CreationDate>
            <LocationConstraint>us-cold</LocationConstraint>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

Create a bucket

A PUT request that is sent to the endpoint root and followed by a string creates a bucket. For more information about endpoints, see Endpoints and storage locations. Bucket names must be globally unique and DNS-compliant. Names between 3 and 63 characters long must be made of lowercase letters, numbers, dots (periods), and dashes (hyphens). Bucket names must begin and end with a lowercase letter or number. Bucket names can’t contain consecutive dots or dashes. Bucket names that resemble IP addresses are not allowed. This operation doesn't use operation-specific query parameters.

Bucket names must be unique because all buckets in the public cloud share a global namespace. This requirement allows for access to a bucket without needing to provide any service instance or account information. It is also not possible to create a bucket with a name beginning with cosv1- or account- as these prefixes are reserved by the system.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Headers
Header	Type	Required?	Description
`ibm-service-instance-id`	String	Yes	This header references the service instance where the bucket is to be created and to which data usage can be billed.
`x-amz-bucket-object-lock-enabled`	Boolean	No	Specifies whether you want to enable Object Lock on the new bucket. This header automatically enables versioning.

When setting Object Lock on a new bucket, ensure that no typographical errors are in the x-amz-bucket-object-lock-enabled header. If either the header or the value is misspelled, the bucket is created, but Object Lock and Versioning is not enabled.

Personally Identifiable Information (PII): When creating buckets or adding objects, do not use any information that can identify any user (natural person) by name, location, or any other means in the name of the bucket or object.

Syntax

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

Example request

The following example creates a bucket that is called 'images'.

PUT /images HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-service-instance-id: {ibm-service-instance-id}

Example request

PUT /images HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example 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 bucket with a different storage class

To create a bucket with a different storage class, send an XML block that specifies a bucket configuration with a LocationConstraint of {provisioning code} in the body of a PUT request to a bucket endpoint. For more information about endpoints, see Endpoints and storage locations. Standard bucket naming rules apply. This operation doesn't use operation-specific query parameters.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

||Header | Type | Description | |--------------------------|--------|--------------------------------------------------------------------------------------------------------------------- | ibm-service-instance-id | String | This header references the service instance where the bucket is to be created and to which data usage can be billed.

Syntax

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

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`CreateBucketConfiguration`	Container	`LocationConstraint`
`LocationConstraint`	String		`CreateBucketConfiguration`	Valid location code

<CreateBucketConfiguration>
  <LocationConstraint>us-vault</LocationConstraint>
</CreateBucketConfiguration>

A list of valid provisioning codes for LocationConstraint can be referenced in the Storage Classes guide.

Example request

The following example creates a bucket that is called 'vault-images'.

PUT /vault-images HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-service-instance-id: {ibm-service-instance-id}
Content-Length: 110

Example request

PUT /vault-images HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

<CreateBucketConfiguration>
  <LocationConstraint>us-vault</LocationConstraint>
</CreateBucketConfiguration>

Example 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 bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP)

To create a bucket where the encryption keys are managed by Key Protect or Hyper Protect Crypto Services, it is necessary to have access to an active Key Protect or Hyper Protect Crypto Services service instance. This operation doesn't use operation-specific query parameters.

For more information about using Key Protect to manage your encryption keys, see the documentation for Key Protect.

For more information about Hyper Protect Crypto Services, see the documentation.

Managed encryption for a Cross Region bucket must use a root key from a Key Protect instance in the nearest high-availability location (us-south or jp-tok).

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Headers
Header	Type	Description
`ibm-service-instance-id`	String	This header references the service instance where the bucket is to be created and to which data usage can be billed.
`ibm-sse-kp-encryption-algorithm`	String	This header is used to specify the algorithm and the key size to use with the encryption key that is stored by using Key Protect. This value must be set to the string `AES256`.
`ibm-sse-kp-customer-root-key-crn`	String	This header is used to reference the specific root key that is used by Key Protect or Hyper Protect Crypto Services to encrypt this bucket. This value must be the full CRN of the root key.

Syntax

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

Example request

The following example creates a bucket that is called 'secure-files'.

PUT /secure-files HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us-south.objectstorage.s3.us-south.cloud-object-storage.appdomain.cloud.net
ibm-service-instance-id: {ibm-service-instance-id}
ibm-sse-kp-encryption-algorithm: "AES256"
ibm-sse-kp-customer-root-key-crn: {customer-root-key-id}

Example request

PUT /secure-files HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-sse-kp-encryption-algorithm: "AES256"
ibm-sse-kp-customer-root-key-crn: {customer-root-key-id}

Example 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

Retrieve a bucket's headers

A HEAD issued to a bucket returns the headers for that bucket.

HEAD requests don't return a body and thus can't return specific error messages such as NoSuchBucket, only NotFound.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Example request

The following example fetches the headers for the 'images' bucket.

HEAD /images HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization:Bearer {token}

Example request

HEAD /images HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example 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

Example request

HEAD requests on buckets with Key Protect encryption return extra headers.

HEAD /secure-files HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization:Bearer {token}

Example request

HEAD /secure-files HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example 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
ibm-sse-kp-enabled: True
ibm-sse-kp-crk-id: {customer-root-key-id}

List objects in a specific bucket (Version 2)

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

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

GET https://{endpoint}/{bucket-name}?list-type=2 # path style
GET https://{bucket-name}.{endpoint}?list-type=2 # virtual host style

Optional query parameters

Optional query parameters
Name	Type	Description
`list-type`	String	Indicates version 2 of the API and the value must be 2.
`prefix`	String	Constrains response to object names that begin 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. The default and maximum value is 1,000.
`fetch-owner`	String	Version 2 of the API does not include the `Owner` information by default. Set this parameter to `true` if `Owner` information is wanted in the response.
`continuation-token`	String	Specifies the next set of objects to be returned when your response is truncated (`IsTruncated` element returns `true`). Your initial response includes the `NextContinuationToken` element. Use this token in the next request as the value for `continuation-token`.
`start-after`	String	Returns key names after a specific key object. This parameter is only valid in your initial request. If a `continuation-token` parameter is included in your request, this parameter is ignored.

Example request (simple)

This request lists the objects inside the "apiary" bucket.

GET /apiary?list-type=2 HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Sample request (simple)

GET /apiary?list-type=2 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response (simple)

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.13.3.57
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Content-Type: application/xml
Content-Length: 814

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <KeyCount>3</KeyCount>
  <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>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>worker-bee</Key>
    <LastModified>2016-08-25T17:46:53.288Z</LastModified>
    <ETag>"d34d8aada2996fc42e6948b926513907"</ETag>
    <Size>467</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Example request (max-keys parameter)

This request lists the objects inside the "apiary" bucket with a max key returned set to 1.

GET /apiary?list-type=2&max-keys=1 HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Sample request (max-keys parameter)

GET /apiary?list-type=2&max-keys=1 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response (Truncated 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.13.3.57
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Content-Type: application/xml
Content-Length: 598

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <NextContinuationToken>1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg</NextContinuationToken>
  <KeyCount>1</KeyCount>
  <MaxKeys>1</MaxKeys>
  <Delimiter/>
  <IsTruncated>true</IsTruncated>
  <Contents>
    <Key>drone-bee</Key>
    <LastModified>2016-08-25T17:38:38.549Z</LastModified>
    <ETag>"0cbc6611f5540bd0809a388dc95a615b"</ETag>
    <Size>4</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Example request (continuation-token parameter)

This request lists the objects inside the "apiary" bucket with a continuation token specified.

GET /apiary?list-type=2&max-keys=1&continuation-token=1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Sample request (continuation-token parameter)

GET /apiary?list-type=2&max-keys=1&continuation-token=1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg  HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response (Truncated Response, continuation-token parameter)

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.13.3.57
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Content-Type: application/xml
Content-Length: 604

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <ContinuationToken>1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg</ContinuationToken>
  <NextContinuationToken>1a8j20CqowRrM4epIQ7fTBuyPZWZUeA8Epog16wYu9KhAPNoYkWQYhGURsIQbll1lP7c-OO-V5Vyzu6mogiakC4NSwlK4LyRDdHQgY-yPH4wMB76MfQR61VyxI4TJLxIWTPSZA0nmQQWcuV2mE4jiDA</NextContinuationToken>
  <KeyCount>1</KeyCount>
  <MaxKeys>1</MaxKeys>
  <Delimiter/>
  <IsTruncated>true</IsTruncated>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

List objects in a specific bucket (deprecated)

This API is included for compatibility with an earlier version. See Version 2 for the recommended method of retrieving objects in a bucket.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Optional query parameters for list object method

Optional query parameters
Name	Type	Description
`prefix`	String	Constrains response to object names that begin 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. The default and maximum value is 1,000.
`marker`	String	Specifies the object from where the listing is to begin, in UTF-8 binary order.

Example request

This request lists the objects inside the "apiary" bucket.

GET /apiary HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Example request

GET /apiary HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example 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 request that is issued to an empty bucket deletes the bucket. The name of the bucket is held in reserve by the system for 10 minutes after the deletion. After 10 minutes, the name is released for re-use. Only empty buckets can be deleted.

If the Object Storage service instance is deleted, all bucket names in that instance are held in reserve by the system for 7 days. After 7 days, the names are released for re-use.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Optional headers

Optional headers
Name	Type	Description
`aspera-ak-max-tries`	String	Specifies the number of times to attempt the delete operation. The default value is 2.

Example request

DELETE /apiary HTTP/1.1
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Example request

DELETE /apiary HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

The server responds with 204 No Content.

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

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

Configure Object Lock on an existing bucket

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

A PUT request that is addressed to an empty bucket with the ?object-lock query parameter sets a new object lock configuration on a bucket.

Syntax

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

The Object Lock configuration is provided as XML in the body of the request. New requests overwrite any existing replication rules that are present on the bucket.

An Object Lock configuration must include one rule.

Headers
Header	Type	Description
`Content-MD5`	String	Required: The Base64 encoded 128-bit MD5 hash of the payload, which is used as an integrity check to ensure that the payload wasn't altered in transit.

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`ObjectLockConfiguration`	Container	`ObjectLockEnabled`, `Rule`	None	Limit 1.
`ObjectLockEnabled`	String	None	`ObjectLockConfiguration`	The only valid value is `ENABLED`.
`Rule`	Container	`DefaultRetention`	`ObjectLockConfiguration`	Limit 1
`DefaultRetention`	Container	`Days`, `Mode`, `Years`	`Rule`	Limit 1.
`Days`	Integer	None	`DefaultRetention`	The number of days that you want to specify for the default retention period. It can't be combined with `Years`.
`Mode`	String	None	`DefaultRetention`	Only `COMPLIANCE` is supported currently.
`Years`	Integer	None	`DefaultRetention`	The number of years that you want to specify for the default retention period. It can't be combined with `Days`.

Example request

This request lists the objects inside the "apiary" bucket.

GET /apiary HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: Bearer {token}

Example 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

<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <ObjectLockEnabled>ENABLED</ObjectLockEnabled>
  <Rule>
      <DefaultRetention>
        <Days>30</Days>
        <Mode>COMPLIANCE</Mode>
      </DefaultRetention>
  </Rule>
</ObjectLockConfiguration>

List canceled or 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.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Parameters

Parameters
Name	Type	Description
`prefix`	String	Constrains response to object names that begin 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. The default and maximum value is 1,000.
`key-marker`	String	Specifies from where the listing is to begin.
`upload-id-marker`	String	Ignored if `key-marker` is not specified, otherwise sets a point at which to begin listing the parts above `upload-id-marker`.

Example request

The following example retrieves all current canceled and incomplete multipart uploads.

GET /apiary?uploads= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

GET /apiary?uploads= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

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

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Example request

The following example lists a CORS configuration on the "apiary" bucket.

GET /apiary?cors= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

GET /apiary?cors= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example 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/">
  <CORSRule>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedOrigin>http://www.ibm.com</AllowedOrigin>
  </CORSRule>
</CORSConfiguration>

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.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Payload Elements

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`CORSConfiguration`	Container	`CORSRule`
`CORSRule`	Container	`AllowedOrigin`, `AllowedMethod`	Delete
`AllowedOrigin`	String		`CORSRule`	Valid origin string
`AllowedMethod`	String		`CORSRule`	Valid method string

The required Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash. The following snippet shows one way to achieve the content for that particular header.

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

Example request

The following example adds a CORS configuration that allows requests from www.ibm.com to issue GET, PUT, and POST requests to the bucket.

PUT /apiary?cors= HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Content-Length: 237

Example request

PUT /apiary?cors= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Content-Length: 237

<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>http://www.ibm.com</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
  </CORSRule>
</CORSConfiguration>

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

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Example request

The following example deletes a CORS configuration for a bucket.

DELETE /apiary?cors= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

DELETE /apiary?cors= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

The server responds with 204 No Content.

List the location constraint for a bucket

A GET issued to a bucket with the proper parameter retrieves the location information for a bucket.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Example request

The following example retrieves the location of the "apiary" bucket.

GET /apiary?location= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

GET /apiary?location= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example response

HTTP/1.1 200 OK
Date: Tue, 12 Jun 2018 21:10:57 GMT
X-Clv-Request-Id: 0e469546-3e43-4c6b-b814-5ad0db5b638f
Accept-Ranges: bytes
Server: Cleversafe/3.13.3.57
X-Clv-S3-Version: 2.5
x-amz-request-id: 0e469546-3e43-4c6b-b814-5ad0db5b638f
Content-Type: application/xml
Content-Length: 161

<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  us-south-standard
</LocationConstraint>

Create a bucket lifecycle configuration

A PUT operation uses the lifecycle query parameter to set lifecycle settings for the bucket. A Content-MD5 header is required as an integrity check for the payload.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Payload Elements

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`LifecycleConfiguration`	Container	`Rule`	None	Limit 1
`Rule`	Container	`ID`, `Status`, `Filter`, `Transition`	`LifecycleConfiguration`	Limit 1
`ID`	String	None	`Rule`	Must consist of (`a-z`,`A-Z`,`0-9`) and the following symbols:`!` `_` `.` `*` `'` `(` `)` `-`
`Filter`	String	`Prefix`	`Rule`	Must contain a `Prefix` element.
`Expiration`	Container	`Days`, `Date`, `ExpiredObjectDeleteMarker`	`Rule`	Limit 1
`Prefix`	String	None	`Filter`	If using a transition (archive) rule, the value must be set to `<Prefix/>`. This limitation does not apply to expiration rules.
`Transition`	Container	`Days`, `StorageClass`	`Rule`	Limit 1 transition rule, and 1000 rules in total.
`Days`	Non-negative integer	None	`Transition`	Must be a value equal to or greater than 0.
`Date`	Date	None	`Transition`	Must be in ISO 8601 Format and the date must be in the f future.
`StorageClass`	String	None	`Transition`	Must be set to `GLACIER` or `ACCELERATED`.
`ExpiredObjectDeleteMarker`	Boolean	None	`Expiration`	Must be `true` or `false`.
`NoncurrentVersionExpiration`	Container	`NoncurrentDays`	`NoncurrentVersionExpiration`	Limit 1
`NoncurrentDays`	Positive Integer	None	`Transition`	Must be a value greater than 0.
`AbortIncompleteMultipartUpload`	Container	`DaysAfterInitiation`	`Rule`	Limit 1
`DaysAfterInitiation`	Non-negative Integer	None	`AbortIncompleteMultipartUpload`	Must be a value greater than 0.

IBM Cloud® Object Storage IaaS (non-IAM) accounts are unable to set the transition storage class to ACCELERATED.

<LifecycleConfiguration>
    <Rule>
        <ID>{string}</ID>
        <Status>Enabled</Status>
        <Filter>
            <Prefix/>
        </Filter>
        <Transition>
            <Days>{integer}</Days>
            <StorageClass>GLACIER</StorageClass>
        </Transition>
    </Rule>
</LifecycleConfiguration>

The required Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash. The following snippet shows one way to achieve the content for that particular header.

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

Example request

PUT /apiary?lifecycle HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: {authorization-string}
Content-Type: text/plain
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Content-Length: 305

Example request

PUT /apiary?lifecycle HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Content-Length: 305
Host: s3.us.cloud-object-storage.appdomain.cloud

<LifecycleConfiguration>
    <Rule>
        <ID>my-archive-policy</ID>
        <Filter>
            <Prefix/>
        </Filter>
        <Status>Enabled</Status>
        <Transition>
            <Days>20</Days>
            <StorageClass>GLACIER</StorageClass>
        </Transition>
    </Rule>
</LifecycleConfiguration>

The server responds with 200 OK.

<LifecycleConfiguration>
    <Rule>
        <ID>{string}</ID>
        <Status>Enabled</Status>
        <Filter>
            <Prefix/>
        </Filter>
        <Expiration>
            <Days>{integer}</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

The required Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash. The following snippet shows one way to achieve the content for that particular header.

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

Example request

PUT /cit-test?lifecycle HTTP/1.1
Host: 192.168.35.22
Date: Fri, 28 Feb 2020 14:12:06 +0000
Authorization: AWS MOfXYiHQ9QTyD2ALoiOh:WrlFRE2KMmhutBf3CxIZoNLl/ko=
Content-MD5: To3JYtaVNR3+aGYtl1dlmw==
Content-Length: 321

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Rule>
    <ID>ID1</ID>
    <Status>Enabled</Status>
    <Filter>
      <Prefix/>
    </Filter>
    <Expiration>
      <Days>100</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Example response The server responds with 200 OK.

We are completely uploaded and fine
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 14:12:06 GMT
X-Clv-Request-Id: 587d909f-4939-41ef-8c16-80aea16a0587
Server: Cleversafe/3.14.9.53
X-Clv-S3-Version: 2.5
x-amz-request-id: 587d909f-4939-41ef-8c16-80aea16a0587
Content-Length: 0

Example request

PUT /{bucket-name}?lifecycle HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
ibm-service-instance-id: {ibm-service-instance-id}
Content-Length: 123

Example request

PUT /{bucket-name}?lifecycle HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 123

Retrieve a bucket lifecycle configuration

A GET operation uses the lifecycle query parameter to retrieve lifecycle settings for the bucket.

Syntax

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

Example request

GET /apiary?lifecycle HTTP/1.1
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Authorization: {authorization-string}

Example request

GET /apiary?lifecycle HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

Example Response

<LifecycleConfiguration>
    <Rule>
        <ID>my-archive-policy</ID>
        <Filter>
            <Prefix/>
        </Filter>
        <Status>Enabled</Status>
        <Transition>
            <Days>20</Days>
            <StorageClass>GLACIER</StorageClass>
        </Transition>
    </Rule>
</LifecycleConfiguration>

Example request

GET /cit_dump-log?lifecycle HTTP/1.1
Host: 192.168.35.22
User-Agent: curl/7.64.1
Accept: */*
Date: Fri, 28 Feb 2020 14:00:43 +0000
Authorization: AWS MOfXYiHQ9QTyD2ALoiOh:iKm2QNetyW740kylP6ja2pze3DM=
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==

Example Response

HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 14:00:43 GMT
X-Clv-Request-Id: ecbf9294-284d-4169-b2cd-5d52b2450808
Server: Cleversafe/3.14.9.53
X-Clv-S3-Version: 2.5
Accept-Ranges: bytes
x-amz-request-id: ecbf9294-284d-4169-b2cd-5d52b2450808
Content-Type: application/xml
Content-Length: 276

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Rule>
    <ID>ID1</ID>
    <Status>Enabled</Status>
    <Filter>
      <Prefix/>
    </Filter>
    <Expiration>
      <Days>270</Days>
    </Expiration>
   </Rule>
</LifecycleConfiguration>

Delete stale data with expiration rules

Any expiration actions for objects that are subject to a bucket's Immutable Object Storage retention policy are deferred until the retention policy is no longer enforced.

For more about using lifecycle configuration to delete objects, check out the documentation.

This implementation of the PUT operation uses the lifecycle query parameter to set lifecycle settings for the bucket. This operation allows for a single lifecycle policy definition for a bucket. The policy is defined as a set of rules that consists of the following parameters: ID, Status, Filter, and Expiration.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Body of the request schema
Header	Type	Description
`Content-MD5`	String	Required: The Base64 encoded 128-bit MD5 hash of the payload, which is used as an integrity check to ensure that the payload wasn't altered in transit.

The following snippet shows one way to achieve the content for that particular header.

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`LifecycleConfiguration`	Container	`Rule`	None	Limit 1.
`Rule`	Container	`ID`, `Status`, `Filter`, `Expiration`	`LifecycleConfiguration`	Limit 1000.
`ID`	String	None	`Rule`	Must consist of (`a-z`,`A-Z`,`0-9`) and the following symbols: `!` `_` `.` `*` `'` `(` `)` `-`
`Filter`	String	`Prefix`	`Rule`	Must contain a `Prefix` element
`Prefix`	String	None	`Filter`	The rule applies to any objects with keys that match this prefix.
`Expiration`	Container	`Days` or `Date`	`Rule`	Limit 1.
`Days`	Non-negative integer	None	`Expiration`	Must be a value greater than 0.
`Date`	Date	None	`Expiration`	Must be in ISO 8601 Format.

Syntax

PUT https://{endpoint}/{bucket}?lifecycle # path style
PUT https://{bucket}.{endpoint}?lifecycle # virtual host style

Example request

PUT /images?lifecycle HTTP/1.1
Host: s3.us.cloud-object-storage.appdomain.cloud
Date: Wed, 7 Feb 2018 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Content-Length: 305

<LifecycleConfiguration>
	<Rule>
		<ID>id1</ID>
		<Filter />
		<Status>Enabled</Status>
		<Expiration>
			<Days>60</Days>
		</Expiration>
	</Rule>
</LifecycleConfiguration>

Delete the lifecycle configuration for a bucket

A DELETE issued to a bucket with the proper parameters removes any lifecycle configurations for a bucket.

Syntax

DELETE https://{endpoint}/{bucket-name}?lifecycle # path style
DELETE https://{bucket-name}.{endpoint}?lifecycle # virtual host style

Example request

DELETE /apiary?lifecycle HTTP/1.1
Authorization: {authorization-string}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

DELETE /apiary?lifecycle HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

The server responds with 204 No Content.

Example request

DELETE /cit-test?lifecycle HTTP/1.1
Host: 192.168.35.22
User-Agent: curl/7.64.1
Accept: */*
Date: Fri, 28 Feb 2020 14:16:47 +0000
Authorization: AWS MOfXYiHQ9QTyD2ALoiOh:n25GU28DiBgkNVgET5hKmLmp938=
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==

Example response

HTTP/1.1 204 No Content
Date: Fri, 28 Feb 2020 14:16:47 GMT
X-Clv-Request-Id: 3e8bdf1e-b611-4b83-a404-e7d3e58e60b0
Server: Cleversafe/3.14.9.53
X-Clv-S3-Version: 2.5
x-amz-request-id: 3e8bdf1e-b611-4b83-a404-e7d3e58e60b0

The server responds with 204 No Content.

Add a retention policy on an existing bucket

Immutable Object Storage is available in certain regions only, see Integrated Services for details. The service also requires a Standard pricing plan. See pricing for details.

Find out more about Immutable Object Storage in the documentation.

The minimum and maximum supported values for the retention period settings MinimumRetention, DefaultRetention, and MaximumRetention are a minimum of 0 days and a maximum of 365243 days (1000 years).

This operation doesn't use extra query parameters. The required Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash. The following snippet shows one way to achieve the content for that particular header.

Policies are enforced until the end of a retention period, and cannot be altered until the retention period has expired. While IBM Cloud® Object Storage uses the S3 API for most operations, the APIs that are used for configuring retention policies are not the same as the S3 API, although some terminology might be shared. Read this documentation carefully to prevent any users in your organization from creating objects that can’t be deleted, even by IBM Cloud administrators.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

Syntax

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

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Constraint
`ProtectionConfiguration`	Container	`Status`, `MinimumRetention`, `MaximumRetention`, `DefaultRetention`
`Status`	String		`ProtectionConfiguration`	Valid status string
`MinimumRetention`	Container	`Days`	`ProtectionConfiguration`
`MaximumRetention`	Container	`Days`	`ProtectionConfiguration`
`DefaultRetention`	Container	`Days`	`ProtectionConfiguration`
`Days`	Integer		`MinimumRetention`, `MaximumRetention`, `DefaultRetention`	Valid retention integer

Example request

PUT /example-bucket?protection= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20181011T190354Z
x-amz-content-sha256: 2938f51643d63c864fdbea618fe71b13579570a86f39da2837c922bae68d72df
Content-MD5: GQmpTNpruOyK6YrxHnpj7g==
Content-Type: text/plain
Host: 67.228.254.193
Content-Length: 299

<ProtectionConfiguration>
  <Status>Retention</Status>
  <MinimumRetention>
    <Days>100</Days>
  </MinimumRetention>
  <MaximumRetention>
    <Days>10000</Days>
  </MaximumRetention>
  <DefaultRetention>
    <Days>2555</Days>
  </DefaultRetention>
</ProtectionConfiguration>

Example response

HTTP/1.1 200 OK
Date: Wed, 5 Oct 2018 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Server: Cleversafe/3.14.1
X-Clv-S3-Version: 2.5
x-amz-request-id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Content-Length: 0

Configure a bucket for static website hosting

A PUT issued to a bucket with the proper parameters creates or replaces a static website configuration for a bucket.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Payload Elements

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Notes
`WebsiteConfiguration`	Container	`ErrorDocument`, `IndexDocument`, `RedirectAllRequestsTo`, `RoutingRule`		Required
`ErrorDocument`	Container	`Key`	`WebsiteConfiguration`
`Key`	String		`ErrorDocument`
`IndexDocument`	Container	`Suffix`	`WebsiteConfiguration`
`Suffix`	String		`IndexDocument`
`RedirectAllRequestsTo`	Container	`HostName`, `Protocol`	`WebsiteConfiguration`	If given, it must be the only element that is specified
`HostName`	String		`RedirectAllRequestsTo`
`Protocol`	String		`RedirectAllRequestsTo`
`RoutingRules`	Container	`RoutingRule`	`WebsiteConfiguration`
`RoutingRule`	Container	`Condition`, `Redirect`	`RoutingRules`
`Condition`	Container	`HttpErrorCodeReturnedEquals`, `KeyPrefixEquals`	`RoutingRule`
`HttpErrorCodeReturnedEquals`	String		`Condition`
`KeyPrefixEquals`	String		`Condition`
`Redirect`	Container	`HostName`, `HttpRedirectCode`, `Protocol`, `ReplaceKeyPrefixWith`, `ReplaceKeyWith`	`RoutingRule`
`HostName`	String		`Redirect`
`HttpRedirectCode`	String		`Redirect`
`Protocol`	String		`Redirect`
`ReplaceKeyPrefixWith`	String		`Redirect`
`ReplaceKeyWith`	String		`Redirect`

Example request

The following example adds a website configuration that serves a basic website that looks for an index.html file in each prefix. For example, a request that is made to /apiary/images/ serves the content in /apiary/images/index.html without the need for specifying the actual file.

PUT /apiary?website HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 119

PUT /apiary?website HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 119

<WebsiteConfiguration>
   <IndexDocument>
      <Suffix>index.html</Suffix>
   </IndexDocument>
</WebsiteConfiguration>

Example response

HTTP/1.1 200 OK
Date: Wed, 5 Oct 2020 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Content-Length: 0

Delete any website configuration for a bucket

A DELETE request that is issued to a bucket with the proper parameters removes the website configuration for a bucket.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

DELETE https://{endpoint}/{bucket-name}?website # path style
DELETE https://{bucket-name}.{endpoint}?website # virtual host style

Example request

The following example deletes a website configuration for a bucket.

DELETE /apiary?website HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

DELETE /apiary?website HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

The server responds with 204 No Content.

Block public ACLs on a bucket

A PUT request that is issued to a bucket with the proper parameters prevents adding public access ACLs on a bucket. It can be set either to fail new ACL requests, or to ignore them. BlockPublicAcls does not affect existing ACLs, but IgnorePublicAcls ignores existing ACLs. This operation does not affect IAM Public Access policies.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

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

Payload Elements

The body of the request must contain an XML block with the following schema:

Body of the request schema
Element	Type	Children	Ancestor	Notes
PublicAccessBlockConfiguration	Container	BlockPublicAcls, IgnorePublicAcls		Required
BlockPublicAcls	Boolean		PublicAccessBlockConfiguration
IgnorePublicAcls	Boolean		PublicAccessBlockConfiguration

Example request

PUT /apiary?publicAccessBlock HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 155

PUT /apiary?publicAccessBlock HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 155

<PublicAccessBlockConfiguration>
   <BlockPublicAcls>True</BlockPublicAcls>
   <IgnorePublicAcls>True</IgnorePublicAcls>
</PublicAccessBlockConfiguration>

Example response

HTTP/1.1 200 OK
Date: Mon, 02 Nov 2020 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Content-Length: 0

Check a public ACL block for a bucket

A GET issued to a bucket with the proper parameters returns the ACL block configuration for a bucket.

Syntax

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

Example request

The following example reads a public access block for a bucket.

GET /apiary?publicAccessBlock HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

GET /apiary?publicAccessBlock HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

HTTP/1.1 200 OK
Date: Mon, 02 Nov 2020 19:52:56 GMT
X-Clv-Request-Id: 7c9079b1-2833-4abc-ba10-466ef06725b2
Server: Cleversafe/3.15.2.31
X-Clv-S3-Version: 2.5
Accept-Ranges: bytes
Content-Type: application/xml
Content-Length: 248

<PublicAccessBlockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <BlockPublicAcls>true</BlockPublicAcls>
   <IgnorePublicAcls>true</IgnorePublicAcls>
</PublicAccessBlockConfiguration>

Delete a public ACL block from a bucket

A DELETE issued to a bucket with the proper parameters removes the public ACL block from a bucket.

Not all operations are supported in Satellite environments. For more information, see supported Satellite APIs

Syntax

DELETE https://{endpoint}/{bucket-name}?publicAccessBlock # path style
DELETE https://{bucket-name}.{endpoint}?publicAccessBlock # virtual host style

Example request

The following example deletes an ACL block for a bucket.

DELETE /apiary?publicAccessBlock HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

Example request

DELETE /apiary?publicAccessBlock HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

The server responds with 204 No Content.

Configure a PUT bucket inventory

A PutBucketInventoryConfiguration issued to a bucket with the proper parameters.

Syntax

PUT {bucket}?inventory&id={id}

Example request

The following example is of a PutBucketInventoryConfiguration request for a bucket.

Example request

PUT /mybucket?inventory&id=myid HTTP/1.1
<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Id>myid</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>my-filter-prefix</Prefix>
    </Filter>
        <IncludedObjectVersions>Current</IncludedObjectVersions>
    <Schedule>
      <Frequency>Daily</Frequency>
    </Schedule>
    <OptionalFields>
              <Field>Size</Field>
            <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
          <Field>IsMultipartUploaded</Field>
          <Field>EncryptionStatus</Field>
          <Field>ObjectOwner</Field>
    </OptionalFields>
        <Destination>
            <S3BucketDestination>
                <Bucket>mybucket</Bucket>
                <Format>CSV</Format>
                <Prefix>my-destination-prefix</Prefix>
              </S3BucketDestination>
        </Destination>
</InventoryConfiguration>

The server responds with 204 No Content.

Configure a GET bucket inventory

A GetBucketInventoryConfiguration issued to a bucket with the proper parameters.

Syntax

GET {bucket}?inventory&id={id}

Example request

The following example is of a GetBucketInventoryConfiguration request for a bucket.

GET mybucket?inventory&id=myid HTTP/1.1

Example response

<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Id>myid</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>my-filter-prefix</Prefix>
    </Filter>
        <IncludedObjectVersions>Current</IncludedObjectVersions>
    <Schedule>
      <Frequency>Daily</Frequency>
    </Schedule>
    <OptionalFields>
              <Field>Size</Field>
            <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
          <Field>IsMultipartUploaded</Field>
          <Field>EncryptionStatus</Field>
          <Field>ObjectOwner</Field>
    </OptionalFields>
        <Destination>
            <S3BucketDestination>
                <Bucket>mybucket</Bucket>
                <Format>CSV</Format>
                <Prefix>my-destination-prefix</Prefix>
              </S3BucketDestination>
        </Destination>
</InventoryConfiguration>

Configure a LIST bucket inventory

A ListBucketInventoryConfigurations issued to a bucket with the proper parameters.

Syntax

GET {bucket}?inventory&continuation-token={continuation-token}

Example request

The following example is of ListBucketInventoryConfigurations request for a bucket.

GET /mybucket?inventory HTTP/1.1

Example response

<?xml version="1.0" encoding="UTF-8"?>
<ListInventoryConfigurationsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <InventoryConfiguration>
          <Id>goodinventoryid</Id>
          <IsEnabled>true</IsEnabled>
          <Filter>
              <Prefix>goodFilterPrefix</Prefix>
          </Filter>
          <Destination>
              <S3BucketDestination>
                  <Format>CSV</Format>
                  <Bucket>mybucketCRN</Bucket>
                  <Prefix>goodPrefix</Prefix>
              </S3BucketDestination>
          </Destination>
          <Schedule>
              <Frequency>Daily</Frequency>
          </Schedule>
          <IncludedObjectVersions>All</IncludedObjectVersions>
          <OptionalFields>
              <Field>Size</Field>
          </OptionalFields>
      </InventoryConfiguration>
      <InventoryConfiguration>
          <Id>goodinventoryid1</Id>
          ...
      </InventoryConfiguration>
      <IsTruncated>true</IsTruncated>
          <NextContinuationToken>{continuation-token}</NextContinuationToken>
</ListInventoryConfigurationsResult>

Configure a DELETE bucket inventory

A DeleteBucketInventoryConfiguration issued to a bucket with the proper parameters.

Syntax

DELETE {bucket}?inventory&id={id}

Example request

The following example is of a DeleteBucketInventoryConfiguration request for a bucket.

DELETE mybucket?inventory&id=myid HTTP/1.1

Example response

204 No Content

Next Steps

For more information, see Object operations.