Using `cURL`

You can get the most out working with the command line in most environments with IBM Cloud® Object Storage and cURL.

Here's a 'cheat sheet' of basic curl commands for the IBM Cloud® Object Storage REST API. More detail can be found in the API reference for buckets or objects.

Using curl assumes a certain amount of familiarity with the command line and Object Storage, and have the necessary information from a service credential, the endpoints reference, or the console. If any terms or variables are unfamiliar, they can be found in the glossary.

Note: Personally Identifiable Information (PII): When naming buckets or objects, do not use any information that can identify any user (natural person) by name, location, or any other means.

Request an IAM Token

Two ways you can generate an IAM oauth token for authenticating requests are using a curl command with an API key (described later), or from the command line by using IBM Cloud® CLI.

Request an IAM token by using an API key

Ensure that you have an API key. You can get one from IBM Cloud® Identity and Access Management.

curl -X "POST" "https://iam.cloud.ibm.com/oidc/token" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "apikey={api-key}" \
     --data-urlencode "response_type=cloud_iam" \
     --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey"

Get your resource instance ID

Some of the following commands require an ibm-service-instance-id parameter. To find this value, go to the Service credentials tab of your Object Storage instance in the cloud console. Create a credential if needed, then use the View credentials menu to see the JSON format. Use the value of resource_instance_id.

For use with curl APIs, you need only the UUID that starts after the last single colon and ends before the final double colon. For example, the ID crn:v1:bluemix:public:cloud-object-storage:global:a/81caa0254631ce5f9330ae427618f209:39d8d161-22c4-4b77-a856-f11db5130d7d:: can be abbreviated to 39d8d161-22c4-4b77-a856-f11db5130d7d.

List buckets

curl "https://(endpoint)/"
 -H "Authorization: bearer (token)"
 -H "ibm-service-instance-id: (resource-instance-id)"

Add a bucket

curl -X "PUT" "https://(endpoint)/(bucket-name)"
 -H "Authorization: Bearer (token)"
 -H "ibm-service-instance-id: (resource-instance-id)"

Add a bucket (storage class)

curl -X "PUT" "https://(endpoint)/(bucket-name)"
 -H "Content-Type: text/plain; charset=utf-8"
 -H "Authorization: Bearer (token)"
 -H "ibm-service-instance-id: (resource-instance-id)"
 -d "<CreateBucketConfiguration>
       <LocationConstraint>(provisioning-code)</LocationConstraint>
     </CreateBucketConfiguration>"

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

Create a bucket CORS

curl -X "PUT" "https://(endpoint)/(bucket-name)/?cors"
 -H "Content-MD5: (md5-hash)"
 -H "Authorization: bearer (token)"
 -H "Content-Type: text/plain; charset=utf-8"
 -d "<CORSConfiguration>
      <CORSRule>
        <AllowedOrigin>(url)</AllowedOrigin>
        <AllowedMethod>(request-type)</AllowedMethod>
        <AllowedHeader>(url)</AllowedHeader>
      </CORSRule>
     </CORSConfiguration>"

The Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash.

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

Get a bucket CORS

curl "https://(endpoint)/(bucket-name)/?cors"
 -H "Authorization: bearer (token)"

Delete a bucket CORS

curl -X "DELETE" "https://(endpoint)/(bucket-name)/?cors"
 -H "Authorization: bearer (token)"

List objects

curl "https://(endpoint)/(bucket-name)"
 -H "Authorization: bearer (token)"

Get bucket headers

curl --head "https://(endpoint)/(bucket-name)/"
 -H "Authorization: bearer (token)"

Get bucket metadata

The use of the config API endpoint isn't the same as the endpoint for your bucket itself. Use of this command returns metadata for the specified bucket.

curl https://config.cloud-object-storage.cloud.ibm.com/v1/b/{my-bucket} \
                        -H 'authorization: bearer <IAM_token>'

Delete a bucket

curl -X "DELETE" "https://(endpoint)/(bucket-name)/"
 -H "Authorization: bearer (token)"

Upload an object

curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)" \
 -H "Authorization: bearer (token)" \
 -H "Content-Type: (content-type)" \
 -d "(object-contents)"

Get an object's headers

curl --head "https://(endpoint)/(bucket-name)/(object-key)"
 -H "Authorization: bearer (token)"

Copy an object

curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)"
 -H "Authorization: bearer (token)"
 -H "x-amz-copy-source: /(bucket-name)/(object-key)"

Check CORS information

curl -X "OPTIONS" "https://(endpoint)/(bucket-name)/(object-key)"
 -H "Access-Control-Request-Method: PUT"
 -H "Origin: http://(url)"

Download an object

curl "https://(endpoint)/(bucket-name)/(object-key)"
 -H "Authorization: bearer (token)"

Check object's ACL

curl "https://(endpoint)/(bucket-name)/(object-key)?acl"
 -H "Authorization: bearer (token)"

Enable a firewall

The use of the config API endpoint isn't the same as the endpoint for your bucket itself. Use of this command enables a firewall for the specified bucket. No other IBM Cloud® services can access the bucket when the firewall is active.

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/{my-bucket} \
                        -H 'authorization: bearer $IAM_TOKEN' \
                        -d '{"firewall": {"allowed_ip": ["10.142.175.0/22", "10.198.243.79"]}}'

Enable activity tracking

Note the use of the config API endpoint isn't the same as the endpoint for your bucket itself. Use of this command enables activity tracking for the specified bucket.

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/{my-bucket} \
                        -H 'authorization: bearer <IAM_token>' \
                        -d '{"activity_tracking": { \
                                "read_data_events": True, \
                                "write_data_events": True}'

Allow anonymous access to an object

curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)?acl"
 -H "Content-Type: (content-type)"
 -H "Authorization: bearer (token)"
 -H "x-amz-acl: public-read"

Delete an object

curl -X "DELETE" "https://(endpoint)/(bucket-name)/(object-key)"
 -H "Authorization: bearer (token)"

Delete many objects

curl -X "POST" "https://(endpoint)/(bucket-name)?delete"
 -H "Content-MD5: (md5-hash)"
 -H "Authorization: bearer (token)"
 -H "Content-Type: text/plain; charset=utf-8"
 -d "<?xml version="1.0" encoding="UTF-8"?>
         <Delete>
           <Object>
             <Key>(first-object)</Key>
           </Object>
           <Object>
             <Key>(second-object)</Key>
           </Object>
         </Delete>"

The Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash.

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

Start a multipart upload

curl -X "POST" "https://(endpoint)/(bucket-name)/(object-key)?uploads"
 -H "Authorization: bearer (token)"

Upload a part

curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)?partNumber=(sequential-integer)&uploadId=(upload-id)"
 -H "Authorization: bearer (token)"
 -H "Content-Type: (content-type)"

Complete a multipart upload

curl -X "POST" "https://(endpoint)/(bucket-name)/(object-key)?uploadId=(upload-id)"
 -H "Authorization: bearer (token)"
 -H "Content-Type: text/plain; charset=utf-8"
 -d "<CompleteMultipartUpload>
         <Part>
           <PartNumber>1</PartNumber>
           <ETag>(etag)</ETag>
         </Part>
         <Part>
           <PartNumber>2</PartNumber>
           <ETag>(etag)</ETag>
         </Part>
       </CompleteMultipartUpload>"

Get incomplete multipart uploads

curl "https://(endpoint)/(bucket-name)/?uploads"
 -H "Authorization: bearer (token)"

Stop incomplete multipart uploads

curl -X "DELETE" "https://(endpoint)/(bucket-name)/(object-key)?uploadId"
 -H "Authorization: bearer (token)"

Configure a Static Website

curl --location --request PUT 'https://<endpoint>/<bucketname>?website' \
--header 'Authorization: bearer <token>' --header 'ibm-service-instance-id: <resource_instance_id> \
--header 'Content-MD5: <hashed-output>' --header 'Content-Type: text/plain' \
--data-raw '<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
    </IndexDocument>
    <ErrorDocument>
        <Key>error.html</Key>
    </ErrorDocument>
</WebsiteConfiguration>'

As a reminder, the Content-MD5 header needs to be the binary representation of a base64-encoded MD5 hash.

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

Next Steps

The detailed description of the RESTful API for IBM Cloud Object Storage can be found in the S3 Compatibility API Documentation or the Configuration API Documentation.

Using cURL

Request an IAM Token

Request an IAM token by using an API key

Get your resource instance ID

List buckets

Add a bucket

Add a bucket (storage class)

Create a bucket CORS

Get a bucket CORS

Delete a bucket CORS

List objects

Get bucket headers

Get bucket metadata

Delete a bucket

Upload an object

Get an object's headers

Copy an object

Check CORS information

Download an object

Check object's ACL

Enable a firewall

Enable activity tracking

Allow anonymous access to an object

Delete an object

Delete many objects

Start a multipart upload

Upload a part

Complete a multipart upload

Get incomplete multipart uploads

Stop incomplete multipart uploads

Configure a Static Website

Next Steps

Using `cURL`