Introduction
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>
GitHub
The code examples on this tab use the client library that is provided for Node.js.
Installation
npm install ibm-cos-sdk
GitHub
The code examples on this tab use the client library that is provided for Python.
Installation
pip install --upgrade ibm-cos-sdk
GitHub
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
GitHub
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.
Methods
No Request Parameters
Status Code
Success
Path Parameters
Status Code
Success
BucketAlreadyExists
BucketAlreadyOwnedByYou
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}?Path Parameters
Query Parameters
Pagination limit
Pagination token
A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria.
When response is truncated (the IsTruncated element value in the response is true), you can use the key name in this field as marker in the subsequent request to get next set of objects. IBM COS lists objects in alphabetical order Note: This element is returned only if you have delimiter request parameter specified. If response does not include the NextMaker and it is truncated, you can use the value of the last Key in the response as the marker in the subsequent request to get the next set of object keys.
Encoding type used to encode object keys in the response.
Possible values: [
url]
Status Code
Success
NoSuchBucket
Check a bucket's headers
This operation is useful to determine if a bucket exists and you have permission to access it.
HEAD /{Bucket}?Path Parameters
Status Code
Success
NoSuchBucket
No Sample Response
Delete a bucket.
Deletes the bucket. All objects in the bucket must be deleted before the bucket itself can be deleted.
DELETE /{Bucket}?Path Parameters
Status Code
Success
No Sample Response
Path Parameters
Object data.
Status Code
Success
Path Parameters
Object data.
Status Code
Success
NoSuchKey
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}Path Parameters
Status Code
Success
NoSuchKey
Path Parameters
Status Code
Success