Introduction

This is a new API for configuring IBM Cloud Object Storage buckets.

This API will evolve to cover the full suite of bucket configuration options provided today by extensions made to the modified S3 API. The COS Resource Configuration API now supports:

  • Viewing non-mutable bucket metadata (CRNs, timestamps, and usage info)
  • Viewing and setting IP address access filters.
  • Viewing and setting Activity Tracker events for object operations.

Unlike the S3 API for to reading and writing data, the Configuration API uses a single, global service endpoint. Whether getting or updating metadata, for buckets located in the eu geo, us-south region, ams01 zone, or any other storage location, the request uses the same endpoint URL: https://config.cloud-object-storage.cloud.ibm.com/v1. Note that the endpoint URL actually contains three parts: a protocol (https://), a host (config.cloud-object-storage.cloud.ibm.com), and a version (v1). The SDKs will construct this by default, but if sending requests using curl or any other REST API utility keep in mind that the endpoint requires both the protocol and version.

The Configuration API supports two HTTP request methods (GET and PATCH) and a single path (/b/{bucket}). GET reads a bucket's metadata, and also returns an Etag header to uniquely identify a bucket's current configuration. The Etag updated when some piece of mutable configuration metadata changes, and can be used with an if-match header in PATCH requests to ensure that you are overwriting what you think you're overwriting. Measure twice, cut once, so to speak.

PATCH operations can update multiple fields in the same request.

What is mutable configuration metadata? There's a lot of useful but non-mutable metadata associated with a bucket: its name, location, class, the service instance it belongs to, the number of objects it holds, and so on. None of those values can be directly edited by a user but are important for intelligent data management and are necessary for integration with other IBM Cloud services. In contrast, mutable bucket metadata adds functionality or alters behavior. In this initial version of the Configuration API, the only such metadata is a bucket's firewall. In future versions of the API, other mutable bucket metadata, such as lifecycle rules, CORS configurations, and retention policies will also be accessible and updatable through the Configuration API.

In direct contrast to an S3 API, the Configuration API doesn't rely on individually defined REST API operations to access different bucket parameters. For instance, in an S3 API you might (theoretically) read the configuration of a bucket firewall by sending GET {endpoint}/{bucket}?firewall, its location with GET {endpoint}/{bucket}?location, and check whether it has Key Protect enabled by sending HEAD {endpoint}/{bucket} and reviewing the response headers. Instead, the Configuration API uses a single JSON document to describe all aspects of a bucket's metadata and configuration with GET {endpoint}/b/{bucket}. For updates, rather than individual REST API operations for different configuration options, the Configuration API uses JSON Merge Patch semantics to make updates directly to the bucket's metadata. Again, while today you can only update a bucket's IP address access filter, in the future it will be possible to add a new lifecycle rule, remove a firewall, and update a default retention period all with a single PATCH request.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Element Description
http_status_code HTTP status code for the response. Integer. Example: 200
code Error code. String. Example: AccessDenied
message Error message. String. Example: Access Denied
resource Target of the failed request. String. Example: Bucket123
ibm_cos_request_id Unique identifier for this request. String. Example: 5043294b-de39-4034-881a-92afbed1453d

Example error object:

{
  "http_status_code": 403,
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token.

To retrieve an access token:

curl -X POST https://iam.cloud.ibm.com/identity/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -H "accept: application/json" \
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To create a client that will automatically handle token management:

const COS = require('ibm-cos-sdk-config')

const clientInfo = {
  iam_apikey: 'apikey',
};

const client = new COS.ResourceConfigurationV1(clientInfo);

Replace apikey with an API key.

Now client is ready to make requests.

To create a client that will automatically handle token management:

from cos_config.resource_configuration_v1 import ResourceConfigurationV1

client = ResourceConfigurationV1(iam_apikey=api_key)

Replace api_key with a valid API key.

Now client is ready to make requests.

Additional headers

Request Parameter Description
authorization Required IBM Cloud IAM bearer token. String.
content-type The content type of the request body. String. Example: application/json.
Response Parameter Description
Date Timestamp of the response. String. Example: Sun, 13 Jan 2019 18:00:56 GMT
Content-Type All responses are of type application/json. String.
Content-Length Length in bytes of the response body. Integer. Example: 255
ETag Entity tag (per RFC 7232) of the current state of configuration. String. Example: "3ee236f6-0f8e-4171-8cec-050e4c87be48"
ibm-cos-config-api-ver The version of this API. String. Example: 1.0
ibm-cos-request-id Unique identifier for this request. String. Example: 5043294b-de39-4034-881a-92afbed1453d

Methods

Returns metadata for the specified bucket.

Returns metadata for the specified bucket.

GET /b/{bucket}
Request

Path Parameters

  • Name of a bucket.

Response

A bucket.

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Precondition Failed

  • Internal Server Error

Example responses

Make changes to a bucket's configuration.

Updates a bucket using JSON Merge Patch. This request is used to add functionality (like an IP access filter) or to update existing parameters. Primitives are overwritten and replaced in their entirety. It is not possible to append a new (or to delete a specific) value to an array. Arrays can be cleared by updating the parameter with an empty array []. Only updates specified mutable fields. Please don't use PATCH trying to update the number of objects in a bucket, any timestamps, or other non-mutable fields.

PATCH /b/{bucket}
Request

Custom Headers

  • An Etag previously returned in a header when fetching or updating a bucket's metadata. If this value does not match the active Etag, the request will fail.

Path Parameters

  • Name of a bucket.

An object containing new configuration metadata.

Response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden

  • Not Found

  • Precondition Failed

  • Internal Server Error

Example responses