Documentation
System StatusPortal Login

Using the API With OpenStack Flex Object Storage

Basic API Concepts with Object Storage for OpenStack Flex

Suggest Edits

Prerequisites

Endpoints

You'll need to know the following two endpoints to make API calls to Swift. They Keystone endpoint is where you make your API call with your credentials to obtain your authentication token. The Keystone endpoint requires you to pass your project name, so you'll need to obtain that ahead of time. Additionally, the Swift endpoint is where you make your storage related API calls. The Swift endpoint will vary by project, so be sure you know your project's ID.

NOTE: Project Name and Project ID are not the same thing. See our guide here where it shows you how to find both.

Placeholders Used in Documentation

Placeholders are denoted by a dollar sign ($) and then all capital lettering. The following are placeholders used in the documentation, and would need to be replaced with your own information or set as variables prior to issuing the API calls that use them:

$USERNAME - Your username that you authenticate with.
$API_KEY - Your user's API key.
$PROJECT_NAME - Your OpenStack Flex Project Name
$TOKEN - Your API Token returned by Identity.
$CONTAINER - Your Object Storage container name.
$FILENAME - Your file name.
$SEGMENTCONTAINER - An Object Storage container for uploading segmented files.

Obtaining a Token:

NOTE: OpenStack Flex Auth Tokens are valid for 12 hours.

Issue the following API call after replacing the placeholders with your own information.

curl -i -X POST <https://keystone.api.iad3.rackspacecloud.com/v3/auth/tokens>   -H "Content-Type: application/json"   -d '{  
    "auth": {  
      "identity": {  
        "methods": ["password"],  
        "password": {  
          "user": {  
            "name": "$USERNAME",  
            "domain": { "name": "rackspace_cloud_domain" },  
            "password": "$API_KEY"  
          }  
        }  
      },  
      "scope": {  
        "project": {  
          "name": "$PROJECT_NAME",  
          "domain": { "name": "rackspace_cloud_domain" }  
        }  
      }  
    }  
  }' | grep x-subject-token

Creating a Container

Issue the following API call after replacing the placeholders with your own information to create a container.

curl -X PUT "<https://swift.api.iad3.rackspacecloud.com/v1/AUTH_abc123defg456789abc123defg567890/$CONTAINER"> -H "X-Auth-Token: $TOKEN"

Uploading a File:

Issue the following API call after replacing the placeholders with your own information to upload a file to a container

curl -v -XPUT -H "X-Auth-Token: $TOKEN" -T ./$FILENAME "<https://swift.api.iad3.rackspacecloud.com/v1/AUTH_abc123defg456789abc123defg567890/$CONTAINER/$FILENAME"> -D -

Working with Large Files

In OpenStack Swift, files cannot exceed 5GB in size. If you want to upload a file larger than 5GB it needs to be segmented out into smaller chunks, uploaded, and then a manifest file uploaded that references the location of those smaller chunks so that it can stitch them back together. The following walks through this process.

Remember to replace placeholder values marked with $CAPITAL text with your own values.

Splitting the File

To split the file you just need to pass the following command on the file in question. 

split -b $SIZE $FILENAME $FILENAME_part_

NOTE: ($SIZE denotes a number and then the digital unit like G, K, M for Gigabytes, Kilobytes, or Megabytes. For example 100M would created segments 100 Megabytes in size.)

Upload the Segments

Now you can iterate over and upload all the segments matching the filename's prefix with a for loop using the command below:

NOTE: $segment in this example is not a placeholder you replace.

for segment in $FILENAME_part_\*; do  
  curl -X PUT  
       -H "X-Auth-Token: $TOKEN"  
       -T "$segment"  
       "<https://swift.api.iad3.rackspacecloud.com/v1/AUTH_abc123defg456789abc123defg567890/$SEGMENTCONTAINER/$FILENAME_segments/$segment">  
done

Upload the Manifest File

The manifest file is a single small file that just containers information on where to find the segments for our file. For ease it's recommended to put the manifest file in another container but the header X-Object-Manifest references where Swift can find the segments to stitch the file back together when it's time to download them.

curl -X PUT  
     -H "X-Auth-Token: $TOKEN"  
     -H "X-Object-Manifest: $SEGMENTCONTAINER/$FILENAME_segments/"  
     -T /dev/null  
     "<https://swift.api.iad3.rackspacecloud.com/v1/AUTH_abc123defg456789abc123defg567890/$CONTAINER/$FILENAME">

Updated 1 day ago