API Overview

Edit online

IBM Cloud Object Storage supports the most commonly used subset of Amazon S3 API operations and includes several IBM extensions, listed in the following tables:

Service operation:

Account operation Note
GET account Used to retrieve a list of all buckets created by the requesting account.

Bucket operations:

Bucket operation Note
GET Bucket Lists objects contained in a bucket. Limited to listing 1,000 objects at once.
PUT Bucket Buckets have naming restrictions. Systems in Vault Mode have a vault limit that also limits the number of buckets.
DELETE Bucket Deletes an empty bucket.
HEAD Bucket Retrieves a bucket’s headers.
GET Bucket CORS Retrieves any cross-origin resource sharing configuration set on a bucket.
PUT Bucket CORS Creates a cross-origin resource sharing configuration for a bucket.
DELETE Bucket CORS Deletes any cross-origin resource sharing configuration set on a bucket.
GET Bucket ACL Retrieves the access control list for a bucket.
PUT Bucket ACL Creates an access control list for a bucket.
GET Bucket Protection Retrieves the protection configuration for a bucket.
PUT Bucket Protection Add protection to a bucket.
GET multipart uploads Lists multipart uploads that have not completed or been canceled.
GET Bucket Tagging (Vault Mode only)
PUT Bucket Tagging (Vault Mode only)
GET Bucket Object Versions Lists versions of an object contained in a bucket.
GET Bucket Versioning Retrieves the versioning configuration for a bucket.
PUT Bucket Versioning Add versioning configuration to a bucket.
GET Bucket Lifecycle Retrieves the Lifecycle configuration for a bucket.
PUT Bucket Lifecycle Add Lifecycle configuration to a bucket.
DELETE Bucket Lifecycle Delete Lifecycle configuration from a bucket.
GET Public Access Block Retrieves the PublicAccessBlock configuration for an S3 bucket.
PUT Public Access Block Creates or modifies the PublicAccessBlock configuration for an S3 bucket.
DELETE Public Access Block Removes the PublicAccessBlock configuration for an S3 bucket.
GET Bucket Policy Status Retrieves the policy status for an S3 bucket, indicating whether the bucket is public.
GET Bucket Website Returns the website configuration for a bucket
PUT Bucket Website Sets the configuration of the website that is specified in the website subresource.
DELETE Bucket Website This action removes the website configuration for a bucket.

Object operations:

Object operation Note
GET Object Retrieves an object from a bucket.
PUT Object Adds an object to a bucket.
DELETE Object Deletes an object from a bucket.
Delete Multiple Objects (POST) Deletes multiple objects from a bucket.
GET Object ACL Retrieves an object’s access control list.
PUT Object ACL Creates an access control list for an object.
GET Object Legal Hold Retrieves a list of legal holds on and the retention period of an object.
POST Object Legal Hold Add or remove a single legal hold from an object.
HEAD Object Retrieves the metadata of an object.
OPTIONS Object Checks CORS configuration to see if a specific request can be sent.
POST Object Adds an object to a bucket using HTML forms.
POST Object Extend Retention Extends the retention period of an object.
PUT Object (Copy) Creates a copy of an object.
Upload Part (PUT) Uploads a part of an object associated with an upload ID.
Upload Part (Copy) (PUT) Uploads a part of an existing object associated with an upload ID.
Initiate Multipart Upload (POST) Creates an upload ID for a given set of parts to be uploaded.
Complete Multipart Upload (POST) Assembles an object from parts associated with an upload ID.
Abort Multipart Upload (DELETE) Aborts upload and deletes outstanding parts associated with an upload ID.
List Parts (GET) Returns a list of parts associated with an upload ID
GET Object Tagging Retrieves the object tagging.
PUT Object Tagging Adds object tagging to an existing object.
DELETE Object Tagging Deletes the object tagging.

The following operations are not supported in the IBM COS implementation of the S3 API:

  • DELETE Bucket analytics
  • DELETE Bucket inventory
  • DELETE Bucket metrics
  • DELETE Bucket policy
  • DELETE Bucket replication
  • GET Bucket accelerate
  • GET Bucket analytics
  • GET Bucket inventory
  • GET Bucket location
  • GET Bucket logging
  • GET Bucket metrics
  • GET Bucket notification
  • GET Bucket policy
  • GET Bucket replication
  • GET Bucket requestPayment
  • List Bucket Analytics Configurations
  • List Bucket Inventory Configurations
  • List Bucket Metrics Configurations
  • PUT Bucket accelerate
  • PUT Bucket analytics
  • PUT Bucket inventory
  • PUT Bucket logging
  • PUT Bucket metrics
  • PUT Bucket notification
  • PUT Bucket policy
  • PUT Bucket replication
  • PUT Bucket requestPayment
  • GET Object torrent
  • POST Object restore

An IBM COS System may be configured in either ‘Vault’ or ‘Container’ mode. In ‘Vault’ mode, a system can contain up to 1,000 ‘Vaults’ (commonly referred to as ‘buckets’ in the S3 API). In ‘Container’ mode, each of the 1,000 ‘Container Vaults’ themselves can hold any number of buckets, each in turn containing any number of objects.