COS Compatibility S3 API - IBM Cloud API Docs

Introduction

Last updated: 2020-03-18

The IBM® Cloud Object Storage API is a REST-based API for reading and writing objects. It uses IBM Cloud® Identity and Access Management for authentication/authorization, and supports a subset of the S3 API for easy migration of applications to IBM Cloud.

For details about using Object Storage, see the IBM Cloud docs.

Object Storage is a global service. The location of data is determined by the region where a bucket is created, and subsequent requests to that bucket must be sent to the same corresponding endpoint. The examples shown here assume that requests are sent to the US South region. For more details about selecting endpoints Object Storage, see the IBM Cloud docs.

This document covers only a subset of methods. For more information about all the methods, see About the IBM Cloud Object Storage S3 API.

Java developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Java. For more information, see the COS SDK for Java API Reference.

JavaScript developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for JavaScript. For more information, see the COS SDK for JavaScript API Reference.

The SDK is supported on Node versions 4.x and later.

Python developers can use this SDK to interact with Object Storage. The SDK is a fork of the boto3 library. For more information, see the COS SDK for Python API Reference.

Go developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Go. For more information, see the COS SDK for Go API Reference.

The SDK supports Go versions 1.10 - 1.12.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cos</groupId>
  <artifactId>ibm-cos-java-sdk</artifactId>
</dependency>
<dependency>
  <groupId>com.ibm.cos</groupId>
  <artifactId>ibm-cos-java-sdk</artifactId>
</dependency>

GitHub

https://github.com/IBM/ibm-cos-sdk-java

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-cos-sdk

npm install ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-js

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade ibm-cos-sdk

pip install --upgrade ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-python

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/ibm-cos-sdk-go

go get -u github.com/IBM/ibm-cos-sdk-go

GitHub

https://github.com/IBM/ibm-cos-sdk-go

Error handling

The Object Storage service uses standard HTTP response codes to indicate if a method completes successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

For more details about response codes Object Storage, see the IBM Cloud docs.

List buckets

Returns a list of all buckets owned by the authenticated sender of the request.

GET /

/

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

ListBucketsOutput

Status Code

200
Success

Example responses

Status 200

{
  "Buckets": [
    {
      "CreationDate": "2012-02-15T21: 03: 02.000Z",
      "Name": "examplebucket"
    },
    {
      "CreationDate": "2011-07-24T19: 33: 50.000Z",
      "Name": "examplebucket2"
    },
    {
      "CreationDate": "2010-12-17T00: 56: 49.000Z",
      "Name": "examplebucket3"
    }
  ],
  "Owner": {
    "DisplayName": "own-display-name",
    "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31"
  }
}
{
  "Buckets": [
    {
      "CreationDate": "2012-02-15T21: 03: 02.000Z",
      "Name": "examplebucket"
    },
    {
      "CreationDate": "2011-07-24T19: 33: 50.000Z",
      "Name": "examplebucket2"
    },
    {
      "CreationDate": "2010-12-17T00: 56: 49.000Z",
      "Name": "examplebucket3"
    }
  ],
  "Owner": {
    "DisplayName": "own-display-name",
    "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31"
  }
}

Create a bucket

Creates a new bucket.

PUT /{Bucket}?

/{Bucket}?

Request

Path Parameters

Bucket
string

Request Body

CreateBucketRequest

Response

Response Body

CreateBucketOutput

Status Code

200
Success
480
BucketAlreadyExists
481
BucketAlreadyOwnedByYou

Example responses

{ "Location": "/examplebucket" }

List objects

Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

GET /{Bucket}?

/{Bucket}?

Request

Path Parameters

Bucket
string

Query Parameters

MaxKeys
string
Pagination limit
Marker
string
Pagination token

Request Body

ListObjectsRequest

Response

Response Body

ListObjectsOutput

Status Code

200
Success
480
NoSuchBucket

Example responses

Status 200

{
  "Contents": [
    {
      "ETag": "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"",
      "Key": "example1.jpg",
      "LastModified": "2014-11-21T19:40:05.000Z",
      "Owner": {
        "DisplayName": "myname",
        "ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Size": 11,
      "StorageClass": "STANDARD"
    },
    {
      "ETag": "\"9c8af9a76df052144598c115ef33e511\"",
      "Key": "example2.jpg",
      "LastModified": "2013-11-15T01:10:49.000Z",
      "Owner": {
        "DisplayName": "myname",
        "ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Size": 713193,
      "StorageClass": "STANDARD"
    }
  ],
  "NextMarker": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ=="
}
{
  "Contents": [
    {
      "ETag": "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"",
      "Key": "example1.jpg",
      "LastModified": "2014-11-21T19:40:05.000Z",
      "Owner": {
        "DisplayName": "myname",
        "ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Size": 11,
      "StorageClass": "STANDARD"
    },
    {
      "ETag": "\"9c8af9a76df052144598c115ef33e511\"",
      "Key": "example2.jpg",
      "LastModified": "2013-11-15T01:10:49.000Z",
      "Owner": {
        "DisplayName": "myname",
        "ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Size": 713193,
      "StorageClass": "STANDARD"
    }
  ],
  "NextMarker": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ=="
}

Check a bucket's headers

This operation is useful to determine if a bucket exists and you have permission to access it.

HEAD /{Bucket}?

/{Bucket}?

Request

Path Parameters

Bucket
string

Request Body

HeadBucketRequest

Response

Status Code

200
Success
480
NoSuchBucket

Delete a bucket.

Deletes the bucket. All objects in the bucket must be deleted before the bucket itself can be deleted.

DELETE /{Bucket}?

/{Bucket}?

Request

Path Parameters

Bucket
string

Request Body

DeleteBucketRequest

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Upload an object

Adds an object to a bucket.

PUT /{Bucket}/{Key}

/{Bucket}/{Key}

Request

Path Parameters

Bucket
string
Key
string

Request Body

PutObjectRequest

Response

Response Body

PutObjectOutput

Status Code

200
Success

Example responses

{ "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", "ServerSideEncryption": "AES256", "VersionId": "CG612hodqujkf8FaaNfp8U..FIhLROcp" }

Download an object

Retrieves objects.

GET /{Bucket}/{Key}

/{Bucket}/{Key}

Request

Path Parameters

Bucket
string
Key
string

Request Body

GetObjectRequest

Response

Response Body

GetObjectOutput

Status Code

200
Success
480
NoSuchKey

Example responses

{ "AcceptRanges": "bytes", "ContentLength": "10", "ContentRange": "bytes 0-9/43", "ContentType": "text/plain", "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"", "LastModified": "Thu, 09 Oct 2014 22:57:28 GMT", "Metadata": {}, "VersionId": "null" }

Check an object''s headers

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.

HEAD /{Bucket}/{Key}

/{Bucket}/{Key}

Request

Path Parameters

Bucket
string
Key
string

Request Body

HeadObjectRequest

Response

Status Code

200
Success
480
NoSuchKey

Delete an object

Deletes an object from a bucket.

DELETE /{Bucket}/{Key}

/{Bucket}/{Key}

Request

Path Parameters

Bucket
string
Key
string

Request Body

DeleteObjectRequest

Response

Response Body

DeleteObjectOutput

Status Code

200
Success

Example responses

{}

Introduction

Error handling

Methods

List buckets

Request

No Request Parameters

Response

Response Body

Buckets

Owner

Status Code

200

Create a bucket

Request

Path Parameters

Bucket

Request Body

CreateBucketConfiguration

Response

Response Body

Status Code

200

480

481

List objects

Request

Path Parameters

Bucket

Query Parameters

MaxKeys

Marker

Request Body

Response

Response Body

IsTruncated

Marker

NextMarker

Contents

Name

Prefix

Delimiter

MaxKeys

CommonPrefixes

EncodingType

Status Code

200

480

Check a bucket's headers

Request

Path Parameters

Bucket

Request Body

Response

Status Code

200

480

Delete a bucket.

Request

Path Parameters

Bucket

Request Body

Response

Status Code

200

No Sample Response

Upload an object

Request

Path Parameters

Bucket

Key

Request Body

Body

Response

Response Body

Status Code

200

Download an object

Request

Path Parameters

Bucket