Rackspace Cloud Files

docs.rackspace.
com/api
Rackspace Cloud Files™ February 21, 2014 API v1
Developer Guide
Rackspace Cloud Files™ Developer Guide

API v1 (2014-02-21)
Copyright © 2009-2014 Rackspace US, Inc. All rights reserved.
This document is intended for software developers interested in developing applications using the Rackspace Cloud Files™ Application
Programming Interface (API). The document is for informational purposes only and is provided “AS IS.”
RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR
COMPLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND
PRODUCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE
WITHOUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT
AS SET FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO
LIABILITY WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any
license to patents, trademarks, copyrights, or other intellectual property.
Rackspace®, Rackspace logo and Fanatical Support® are registered service marks of Rackspace US, Inc. All other product names and
trademarks used in this document are for identification purposes only and are property of their respective owners.
ii
Developer Guide
Table of Contents
1. Overview ..................................................................................................................... 1
1.1. Intended Audience ........................................................................................... 1
1.2. Document Change History ................................................................................ 2
1.3. Additional Resources ........................................................................................ 4
1.4. Pricing and Service Level ................................................................................... 5
2. Concepts ..................................................................................................................... 6
2.1. Accounts .......................................................................................................... 6
2.2. Authentication ................................................................................................. 6
2.3. Permissions ....................................................................................................... 6
2.4. Containers ........................................................................................................ 6
2.5. Objects ............................................................................................................. 7
2.6. Operations ....................................................................................................... 7
2.7. CDN-enabled Containers ................................................................................... 8
2.8. Language-Specific APIs ..................................................................................... 9
3. General API Information ........................................................................................... 10
3.1. Authentication ............................................................................................... 10
3.1.1. Geographic Endpoints .......................................................................... 10
3.1.2. Retrieving the Authentication Token .................................................... 10
3.2. Role Based Access Control .............................................................................. 19
3.2.1. Assigning Roles to Account Users ......................................................... 19
3.2.2. Roles Available for Cloud Files .............................................................. 19
3.2.3. Resolving Conflicts Between RBAC Multiproduct vs. Custom (Product-
specific) Roles ................................................................................................ 20
3.2.4. RBAC Permissions Cross-reference to Cloud Files API Operations ............ 20
3.3. Service Access Endpoints ................................................................................. 20
3.4. Cloud Files Service Contract Version ................................................................ 22
3.5. Absolute Limits ............................................................................................... 23
3.6. Request and Response Types .......................................................................... 23
4. Overview of API Operations ...................................................................................... 24
5. API Operations for Storage Services ........................................................................... 26
5.1. Account Services ............................................................................................. 27
5.1.1. List Account Containers ....................................................................... 28
5.1.2. Create or Update Account Metadata ................................................... 32
5.1.3. Get Account Metadata ........................................................................ 34
5.1.4. Delete Account Metadata .................................................................... 36
5.2. Container Services .......................................................................................... 36
5.2.1. List Container Objects .......................................................................... 38
5.2.2. Create Container ................................................................................. 42
5.2.3. Delete Container .................................................................................. 44
5.2.4. Create or Update Container Metadata ................................................. 45
5.2.5. Get Container Metadata ...................................................................... 47
5.2.6. Delete Container Metadata .................................................................. 49
5.3. Object Services ............................................................................................... 50
5.3.1. Get Object Data .................................................................................. 51
5.3.2. Create or Update Object ...................................................................... 54
5.3.3. Delete Object ...................................................................................... 57
5.3.4. Copy Object ......................................................................................... 59
5.3.5. Get Object Metadata ........................................................................... 62
iii
Developer Guide
5.3.6. Update Object Metadata ..................................................................... 64

6. Pseudo Hierarchical Folders and Directories ............................................................... 66
7. Additional Container Services Information ................................................................. 68
7.1. Container Quotas ........................................................................................... 68
7.2. Access Log Delivery ........................................................................................ 68
8. Additional Object Services Information ...................................................................... 70
8.1. Chunked Transfer Encoding ............................................................................ 70
8.2. Create Large Objects ...................................................................................... 70
8.2.1. Dynamic Large Object Creation ............................................................ 72
8.2.2. Static Large Object Creation ................................................................ 74
8.3. Enabling File Compression with the Content-Encoding Header ......................... 78
8.4. Enabling Browser Bypass with the Content-Disposition Header ........................ 78
8.5. Expiring Objects with the X-Delete-After and X-Delete-At Headers....... 78
8.6. Object Versioning ........................................................................................... 79
9. API Operations for CDN Services ............................................................................... 82
9.1. CDN Account Services ..................................................................................... 82
9.1.1. List CDN-Enabled Containers ................................................................ 83
9.2. CDN Container Services .................................................................................. 84
9.2.1. CDN-Enable and CDN-Disable a Container ............................................ 86
9.2.2. List a CDN-Enabled Container's Metadata ............................................. 89
9.2.3. Update CDN-Enabled Container Metadata ........................................... 92
9.3. CDN Object Services ....................................................................................... 93
9.3.1. Delete CDN Object .............................................................................. 94
10. Additional CDN Services Information ....................................................................... 96
10.1. Purge CDN-Enabled Containers ..................................................................... 96
10.2. CDN-Enabled Containers Served through SSL ................................................. 96
10.3. Streaming CDN-Enabled Containers ............................................................... 97
10.4. iOS Streaming ............................................................................................... 97
11. Static Websites Using CDN-Enabled Containers ........................................................ 99
11.1. Create Static Website .................................................................................... 99
11.2. Set Error Pages for Static Website ............................................................... 100
12. Bulk Operations ..................................................................................................... 102
12.1. Bulk Importing of Data ............................................................................... 102
12.2. Extract Archive ........................................................................................... 102
12.3. Bulk Delete ................................................................................................. 104
13. Public Access to Your Cloud Files Account .............................................................. 107
13.1. TempURL .................................................................................................... 107
13.1.1. Set Account TempURL Metadata Key ............................................... 107
13.1.2. Create the TempURL ........................................................................ 108
13.1.3. Override TempURL File Names ......................................................... 109
13.2. FormPost .................................................................................................... 110
13.2.1. Set Account Metadata Key ............................................................... 110
13.2.2. Create the Form ............................................................................... 110
13.3. CORS .......................................................................................................... 112
14. Examples and Troubleshooting .............................................................................. 116
14.1. Using cURL ................................................................................................. 116
14.2. Authentication with cURL ........................................................................... 116
14.3. Determining Storage Usage with cURL ........................................................ 118
14.4. Creating a Storage Container with cURL ...................................................... 118
14.5. Uploading a Storage Object with cURL ........................................................ 119
14.6. CDN-Enabling the Container with cURL ....................................................... 119
iv
Developer Guide
14.7. Other cURL Commands ............................................................................... 121

Glossary ....................................................................................................................... 122
v
Developer Guide
List of Figures
4.1. Cloud Files System Interfaces .................................................................................. 25
vi
Developer Guide
List of Tables
3.1. Cloud Files Product Roles and Permissions ............................................................... 19
3.2. Multiproduct (Global) Roles and Permissions ........................................................... 20
3.3. Regionalized Service Endpoints for Storage Services ................................................ 20
3.4. Regionalized Service Endpoints for CDN Management Services ................................ 22
3.5. Absolute Limits ....................................................................................................... 23
5.1. Cloud Files Supported Range Formats ..................................................................... 51
7.1. Metadata Values for Setting Container Quotas ....................................................... 68
8.1. Comparison of Static and Dynamic Large Objects .................................................... 72
13.1. Supported CORS Container Headers .................................................................... 113
vii
Developer Guide
List of Examples
3.1. Auth Request: XML ................................................................................................ 10
3.2. Auth Request: JSON ............................................................................................... 11
3.3. Auth Response: XML .............................................................................................. 12
3.4. Auth Response: JSON ............................................................................................. 14
3.5. Example Request URL (contract version in bold) ..................................................... 22
5.1. List Account Containers Request: XML .................................................................... 30
5.2. List Account Containers Request: JSON ................................................................... 30
5.3. List Account Containers Response: XML .................................................................. 31
5.4. List Account Containers Response: JSON ................................................................. 31
5.5. Create or Update Account Metadata Request ......................................................... 32
5.6. Create or Update Account Metadata Response ....................................................... 32
5.7. Get Account Metadata Request .............................................................................. 34
5.8. Get Account Metadata Response ............................................................................ 34
5.9. Delete Account Metadata Request ......................................................................... 36
5.10. Delete Account Metadata Response ..................................................................... 36
5.11. List Container Objects Request .............................................................................. 40
5.12. List Container Objects Request: XML ..................................................................... 40
5.13. List Container Objects Request: JSON .................................................................... 40
5.14. List Container Objects Response ............................................................................ 40
5.15. List Container Objects Response: XML ................................................................... 41
5.16. List Container Objects Response: JSON .................................................................. 41
5.17. Create Container Request ..................................................................................... 42
5.18. Create Container with Metadata Request ............................................................. 43
5.19. Create Container Response ................................................................................... 43
5.20. Create Container with Metadata Response ........................................................... 43
5.21. Delete Container Request ..................................................................................... 44
5.22. Delete Container Response ................................................................................... 44
5.23. Create or Update Container Metadata Request ..................................................... 45
5.24. Create or Update Container Metadata Response ................................................... 46
5.25. Get Container Metadata Request .......................................................................... 47
5.26. Get Container Metadata Response ....................................................................... 48
5.27. Delete Container Metadata Request ..................................................................... 49
5.28. Delete Container Metadata Response ................................................................... 49
5.29. Get Object Data Request ...................................................................................... 52
5.30. Get Object Data Request Using Range .................................................................. 52
5.31. Get Object Data Request Using Multiple Ranges ................................................... 52
5.32. Get Object Data Response .................................................................................... 52
5.33. Get Object Data Response Using Range ................................................................ 52
5.34. Get Object Data Response Using Multiple Ranges ................................................. 53
5.35. Create or Update Object Request ......................................................................... 55
5.36. Create or Update Object Response ....................................................................... 56
5.37. Delete Object Request .......................................................................................... 57
5.38. Delete Object Response ........................................................................................ 57
5.39. Copy Object Method 1 - Using PUT ....................................................................... 59
5.40. Copy Object Method 2 - Using COPY .................................................................... 59
5.41. Data Center Endpoints ......................................................................................... 60
5.42. Copy Object Request Using PUT ............................................................................ 61
5.43. Copy Object Request Using COPY ......................................................................... 61
viii
Developer Guide
5.44. Get Object Metadata Request .............................................................................. 62

5.45. Get Object Metadata Response ............................................................................ 63
5.46. Update Object Metadata Request ......................................................................... 65
5.47. Update Object Metadata Response ....................................................................... 65
7.1. Example Access Log Entries .................................................................................... 69
8.1. Upload Unspecified Quantity of Content Request ................................................... 70
8.2. Upload Unspecified Quantity of Content Response ................................................. 70
8.3. Upload Segment of a Large Object Request ............................................................ 73
8.4. Upload Segment of a Large Object Response .......................................................... 73
8.5. Upload Next Segment of the Large Object Request ................................................. 74
8.6. Upload Next Segment of the Large Object Response ............................................... 74
8.7. Upload Manifest Request ....................................................................................... 74
8.8. Upload Manifest Response ..................................................................................... 74
8.9. Static Large Object Manifest List ............................................................................. 76
8.10. Request with Content-Encoding ............................................................................ 78
8.11. Request with Content-Disposition ......................................................................... 78
8.12. X-Delete-At Request .............................................................................................. 79
8.13. X-Delete-After Request ......................................................................................... 79
8.14. Object Versioning with cURL ................................................................................. 80
9.1. CDN-Enabled Containers List Request ...................................................................... 84
9.2. CDN-Enabled Containers List Response ................................................................... 84
9.3. CDN-Enable Container Request ............................................................................... 87
9.4. CDN-Disable Container Request .............................................................................. 87
9.5. CDN-Enable Container Response ............................................................................. 88
9.6. List a CDN-Enabled Container's Metadata Request .................................................. 89
9.7. List a CDN-Enabled Container's Metadata Request: JSON ......................................... 89
9.8. List a CDN-Enabled Container's Metadata Request: XML ......................................... 90
9.9. Get CDN-Enabled Container Metadata Request ....................................................... 90
9.10. List a CDN-Enabled Container's Metadata Response: JSON ..................................... 90
9.11. List a CDN-Enabled Container's Metadata Response: XML ...................................... 91
9.12. Update CDN-Enabled Container Metadata Request ............................................... 92
9.13. Update CDN-Enabled Container Metadata Response ............................................. 93
9.14. Delete CDN-enabled Object Request ..................................................................... 95
9.15. Delete CDN-Enabled Object Response ................................................................... 95
10.1. CDN-Enabled Container Metadata Request with SSL .............................................. 96
10.2. CDN-Enabled Container Metadata Response with SSL ............................................ 96
10.3. CDN-Enabled Container Metadata Request with Streaming Enabled ...................... 97
10.4. CDN-Enabled Container Metadata Response with Streaming Enabled .................... 97
10.5. HTML 5 Video Element ......................................................................................... 98
10.6. JavaScript for User Agent Check ........................................................................... 98
10.7. Load JavaScript in HTML page .............................................................................. 98
11.1. Set up Static Web ............................................................................................... 100
11.2. Container Setup for Static Website ..................................................................... 100
11.3. Static Website Enabled Container Results ............................................................ 100
11.4. Set Error Pages for Static Website Request .......................................................... 101
12.1. Extract Archive Response .................................................................................... 103
12.2. Extract Archive Response with Errors .................................................................. 103
12.3. Bulk Delete Response .......................................................................................... 105
12.4. Bulk Delete Response with Errors ........................................................................ 105
13.1. Set Account Metadata Key for Public Access ....................................................... 107
13.2. Create TempURL (in python) .............................................................................. 108
ix
Developer Guide
13.3. Create TempURL (in PHP) ................................................................................... 108

13.4. Create TempURL (in Ruby) .................................................................................. 109
13.5. TempURL without File Name Override ................................................................ 110
13.6. TempURL with File Name Override ...................................................................... 110
13.7. Set Account Metadata Key for Public Access Request .......................................... 110
13.8. Layout of Web Form .......................................................................................... 111
13.9. Generate Signature for Form Post ....................................................................... 112
13.10. CORS POST Request .......................................................................................... 114
13.11. Test CORS Page ................................................................................................ 114
14.1. cURL Authenticate Request with Username and API Key Credentials and
Response:JSON ............................................................................................................ 116
14.2. cURL Get Storage Space ...................................................................................... 118
14.3. cURL Create Storage Container ........................................................................... 118
14.4. cURL Upload Storage Object ............................................................................... 119
14.5. cURL CDN-Enable Container ................................................................................ 120
14.6. cURL Download a File ......................................................................................... 120
x
Developer Guide
1. Overview
Rackspace Cloud Files™ is an affordable, redundant, scalable, and dynamic storage service
offering. The core storage system is designed to provide a secure, network-accessible way
to store an unlimited number of files. Each file can be as large as 5 gigabytes. You can store
as much as you want and pay only for storage space that you actually use.
Additionally, Cloud Files provides a simple yet powerful way to publish and distribute
content behind a Content Distribution Network. As a Cloud Files user, you get access to
this network automatically without having to worry about contracts, additional costs, or
technical hurdles.
Cloud Files allows you to store and retrieve files and CDN-enabled content through a simple
Web Services interface (REST: Representational State Transfer). There are also language-
specific APIs that utilize the RESTful API but make it much easier for developers to integrate
into their applications.
For more details on the Cloud Files service, please refer to http://www.rackspace.com/
cloud/files/ and to the Knowledge Center article Best Practices for Using Cloud Files.
Rackspace welcomes feedback, comments, and bug reports at

[email protected].
1.1. Intended Audience
This guide is intended to assist software developers who want to develop applications
using the Rackspace Cloud Files API. It fully documents the REST application programming
interface (API) that allows developers to interact with the storage and CDN components
of the Cloud Files system. To use the information provided here, you should first have a
general understanding of the Rackspace Cloud Files service and have access to an active
Rackspace Cloud Files account. You should also be familiar with:
• RESTful web services

• HTTP/1.1
System administrators and others interested in the storage and CDN benefits of Cloud Files
should consider using the File Manager interface within the Rackspace Cloud Control Panel,
Jungle Disk, or third party tools such as Fileuploader or Cyberduck. The Rackspace Cloud
Control Panel provides an easy to use web-based interface for uploading and downloading
content to and from Cloud Files.
Rackspace also provides language-specific APIs in several popular programming languages.

For customers who are interested in accessing Cloud Files using one of the language-specific
APIs, refer to Rackspace Cloud SDKs Software Development Kit Guide. For information in
this book about language-specific APIs, refer to Language-Specific API Bindings.
1
Developer Guide
1.2. Document Change History

This version of the Developer Guide replaces and obsoletes all earlier versions. The most
recent changes are described in the table below:
Revision Date Summary of Changes
February 21, 2014 • Updated the table in Section 3.5, “Absolute Limits” [23] to include the rate limit for write
operations, which is 100 operations per second per container.
• Updated the following object methods to include the X-Detect-Content-Type header

in the request:
• PUT (Create or Update Object)
• POST (Update Object Metadata)
• COPY (Copy Object)
If you set this header to True, the Content-Type that is sent in the request (if any) is
ignored, and Content-Type is guessed by using the Python mimetypes library based on
the object path.
• Reworked Chapter 5, “API Operations for Storage Services” [26] and Chapter 9, “API
Operations for CDN Services” [82] by using Web Application Description Language
(WADL) files for the resource and method descriptions.
December 31, 2013 • Updated the instructions for locating the API Key in the Cloud Control Panel in Section 3.1.2,
“Retrieving the Authentication Token” [10].
• Added a table of all API operations, which lists and briefly describes all API operations. Also
added tables showing the API operations at the beginning of each section that describes the
operations.
• Added service access endpoints for the CDN management service component to Section 3.3,
“Service Access Endpoints” [20].
• Updated account information in Section 3.3, “Service Access Endpoints” [20] to show

MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee rather than 1234.
• Added Section 3.4, “Cloud Files Service Contract Version” [22].
• Added Section 3.5, “Absolute Limits” [23].
• Added Section 3.6, “Request and Response Types” [23].
• Added Section 5.1.2, “Create or Update Account Metadata” [32].
• Added Section 5.1.4, “Delete Account Metadata” [36].
• In all examples, updated the X-Auth-Token to use the current format returned by an
authentication request (no dashes). Also updated examples to use real values for account,
container, and object.
November 26, 2013 • Added Section 8.2, “Create Large Objects” [70] with more information about Dynamic
Large Objects and Static Large Objects.
• Updated Section 12.2, “Extract Archive” [102] to include a note about using a blank
Content-Type to have Cloud Files determine the file type for the archive.
November 22, 2013 • Added service catalog information for cloudfilesCDN endpoints (Section 3.3, “Service
Access Endpoints” [20]).
• Made miscellaneous updates throughout this book to improve wording and consistency.
November 1, 2013 • Replaced references to X-Storage-Url and X-Cdn-Management–Url throughout this
document with references to the cloudFiles and cloudFilesCDN endpoints in the
service catalog based on use of Identity v2.0 rather than Identity v1.0.
• Updated Section 2.2, “Authentication” [6] to include new references to additional

information about the service access endpoints and the service catalog.
2
Developer Guide

• Updated Section 14.2, “Authentication with cURL” [116] to show a cURL example for
Identity v2.0 only.
October 25, 2013 • Added Section 3.3, “Service Access Endpoints” [20], which includes all endpoints for
Cloud Files including the newest one in Hong Kong.
• Updated Section 3.1, “Authentication” [10] to show information for Rackspace Identity

v2.0.
• Updated Section 13.2.2, “Create the Form” [110] to indicate that the value of redirect
(see Example 7.9) can be empty to indicate that no redirect is included on the form.
September 26, 2013 • Added Section 3.2, “Role Based Access Control” [19].
• Updated Section 13.3, “CORS ” [112].

September 19, 2013 • Updated responses to show application/json in Section 12.3, “Bulk Delete” [104].
• Added X-Container-Meta-Web-Listings, X-Container-Meta-Web-Listings-

Css, and X-Container-Meta-Web-Directory-Type to Section 11.1, “Create Static
Website” [99].
July 18, 2013 • Clarified information about redirect and expires in Section 13.2.2, “Create the
Form” [110].
July 2, 2013 • Corrected Example 7.1 (back to using Identity v1.0) in Section 14.2, “Authentication with
cURL” [116] and added an example for Identity v2.0.
June 27, 2013 • In Section 3.1, “Authentication” [10], changed references for authentication to point to
v2.0.
• In Section 14.2, “Authentication with cURL” [116], updated the example to show v2.0 for
authentication.
• In Section 9.3, “CDN Object Services” [93] and Section 9.3.1, “Delete CDN

Object” [94], added a note about removing a CDN-enabled container by setting X-Cdn-
Enabled to False in HEAD.
June 14, 2013 • Added information about authentication, v1 and v2, in Section 3.1,
“Authentication” [10].
May 20, 2013 • Added a link in Chapter 1, “Overview” [1] to the Knowledge Center article, "Best Practices
for Using Cloud Files," at http://www.rackspace.com/knowledge_center/article/best-
practices-for-using-cloud-files.
• Added Section 7.1, “Container Quotas” [68]
• Created a new section Section 5.3, “Object Services” [50]. This section includes new and
previously existing information specifically related to storage objects.
• Added Section 8.2.2, “Static Large Object Creation” [74].
• Added Chapter 12, “Bulk Operations ” [102].
• Added Section 13.1.3, “Override TempURL File Names” [109].
February 1, 2013 • Changed location of SDKs. Added note on object metadata behavior.
December 5, 2012 • Added iOS Streaming.
November 30, 2012 • Fixed internal linking.
November 16, 2012 • Added end_marker list parameter and CORS container headers.
October 31, 2012 • Updated language binding language and links.
• Updated view CDN-enabled header.
October 1, 2012 • Added Access Log Delivery. Updated auth point.
September 25, 2012 • Added multi-region, legal, and CDN charge note.
August 13, 2012 • Changed TTL limits and CDN URLs.
July 23, 2012 • Added CDN object purge limits.
June 12, 2012 • Added Bulk Import information.
June 1, 2012 • Added Object Versioning and Static Web information.
April 25, 2012 • Added TempURL and FormPost.
March 19, 2012 • Fixed doc tickets.
3
Developer Guide

February 6, 2012 • Revisions to clarify issues brought up in doc tickets. Formatted HEAD like other commands.
Standardized on URL. Added Expiring Objects and ServiceNet information.
January 12, 2012 • Revisions for the addition of expiring object functionality plus doc bug fixes including adding
more cross-references for finding language bindings.
November 15, 2011 • Revised information about how to perform a CDN purge, indicating you must contact
support to request a container purge operation.
October 21, 2011 • Added more detail about reasons to perform a CDN purge, clarifying that it is not required
for deleting objects.
September 13, 2011 • Added information about streaming containers to support this new streaming feature,
including changing examples to match the streaming headers and URLs returned.
June 29, 2011 • In the 6.1.1 Authorization example, changed X-Auth-Token to X-Auth-Key.
June 15, 2011 • Added best practices for authentication tokens.
May 24, 2011 • Added information about new headers including CORS headers.
April 20, 2011 • HEAD returns 200 instead of 204 on an object metadata request.
• TTL maximum value is now 50 years instead of 3 days, the minimum TTL is now 15 minutes
(900 seconds), and the default is now 72 hours instead of 24 hours.
March 25, 2011 • Added information about large object support.
March 17, 2011 • Added information about container metadata.
March 10, 2011 • Added a section about retrieving an SSL URL for CDN-enabled containers that are using
https protocol.
• Updated examples to contain SSL as appropriate.
February 25, 2011 • Added information about the edge purge capability for CDN-enabled containers and
objects.
February 18, 2011 • Fixed error in the header range example that stated first instead of last when fetching a
portion of the data.
• Updated CDN URLs to match new format.
• Fixed error referring to X-Auth-User instead of X-Auth-Key.
January 12, 2011 • Removed references to ACL (Access Control List).
• Fixed error in examples referring to X-Auth-Key where it should be X-Auth-Token.
• Added section numbers.
January 4, 2011 • Expanded authentication information for UK release.
• Added delimiter as a Query Parameter and server-side object copy example.
May 5, 2008 • Initial release.
1.3. Additional Resources
You can download the most current version of this document from the Rackspace Cloud
website at docs.rackspacecloud.com/files/api/cf-devguide-latest.pdf.
For more details about the Cloud Files service, please refer to http://www.rackspace.com/
cloud/files/. Related documents are available at the same site, as are links to official
Rackspace support channels, including Knowledge Center articles, forums, phone, chat, and
email.
For information about the Rackspace language-specific APIs that you can use for Cloud
Files, refer to Rackspace Cloud SDKs Software Development Kit Guide. Each language-
specific API includes its own documentation (either HTML, PDF, or CHM) including code
snippets and examples to help you get started. For information in this book about the
language-specific APIs, refer to Language-Specific API Bindings.
4
Developer Guide
1.4. Pricing and Service Level

Cloud Files is part of the Rackspace Cloud and your use through the API will be billed
according to the pricing schedule at www.rackspace.com/cloud/public/files/pricing.
The Service Level Agreement (SLA) for Cloud Files is available at http://
www.rackspace.com/information/legal/cloud/sla#files.
5
Developer Guide
2. Concepts
Cloud Files is not a file system in the traditional sense. You will not be able to map or
mount virtual disk drives like you can with other forms of storage such as a SAN or NAS.
Since Cloud Files is a different way of thinking when it comes to storage, you should take a
few moments to review the key concepts listed below.
2.1. Accounts
The Cloud Files system is designed to be used by many different customers. Your user
account is your portion of the Cloud Files system. You must identify yourself with
your Rackspace Cloud user name and API access key and once authenticated, you
have full read/write access to the files stored under your account. Please visit http://
www.rackspacecloud.com/signup to obtain a Cloud Files account and enable your API
access key.
2.2. Authentication
Section 3.1, “Authentication” [10] describes how to authenticate against the Rackspace
Cloud Identity service to receive Cloud Files connection parameters and an authentication
token. The token must be passed in for Cloud Files operations during the time it is valid.
For more information about authentication, see the Cloud Identity Client Developer Guide,
v2.0 at docs.rackspace.com.
Note
The language-specific APIs handle authentication, token passing, and HTTPS
request/response communication.
2.3. Permissions
In Cloud Files, you have your own storage account and has full access to that
account. You must authenticate with your credentials as described in Section 3.1,
“Authentication” [10], but once authenticated you can perform all Cloud Files
operations within that account.
2.4. Containers
A container is a storage compartment that provides a way for you to organize your data.
You can think of a container as a folder in Windows® or a directory in UNIX®. The primary
difference between a container and these other file system concepts is that containers
cannot be nested. You can have up to 500,000 containers in your account. Data must be
stored in a container so you must have at least one container defined in your account prior
to uploading data.
If you expect to write more than 100 objects per second to a single container, we
recommend organizing those objects across multiple containers to improve performance.
6
Developer Guide
The only restrictions on container names is that they cannot contain a forward slash (/) and
must be less than 256 bytes in length. Note that the length restriction applies to the name
after it has been URL-encoded. For example, a container name of Course Docs would be
URL-encoded as Course%20Docs and is 13 bytes in length rather than the expected 11.
You can create a container in any Rackspace data center. (See Section 3.3, “Service Access
Endpoints” [20] for a list.) However, in order to lower your costs, you should create
your most served containers in the same data center as your server. Otherwise, you will
be billed for external bandwidth charges. Note that this is true when computations are
performed on objects but is not true for static content served to end users directly.
2.5. Objects
Objects are the basic storage entities in Cloud Files. They represent the files and their
optional metadata you upload to the system. When you upload objects to Cloud Files,
the data is stored as-is (without compression or encryption) and consists of a location
(container), the object's name, and any metadata you assign consisting of key/value pairs.
For instance, you can choose to store a backup of your digital photos and organize them
into albums. In this case, each object could be tagged with metadata such as Album :
Caribbean Cruise or Album : Aspen Ski Trip.
The only restriction on object names is that they must be less than 1024 bytes in length
after URL-encoding. For example, an object name of C++final(v2).txt should be URL-
encoded as C%2B%2Bfinal%28v2%29.txt and therefore be 24 bytes in length rather
than the expected 16.
Cloud Files has a limit on the size of a single uploaded object. By default this limit is 5 GB.
However, the download size of a single object is virtually unlimited with the concept of
segmentation. Segments of the larger object are uploaded and a special manifest file is
created that, when downloaded, sends all the segments concatenated as a single object.
This also offers much greater upload speed with the possibility of parallel uploads of the
segments.
For metadata, you should not exceed 90 individual key/value pairs for any one object and
the total byte length of all key/value pairs should not exceed 4KB (4096 bytes).
2.6. Operations
Operations are the actions you perform within your account, such as creating or deleting
containers or uploading or downloading objects. The full list of operations is given in
Chapter 5, “API Operations for Storage Services” [26]. The operations are then
described in the following REST API sections;
• Section 2.1, “Accounts” [6]
• Section 2.4, “Containers” [6]
• Section 2.5, “Objects” [7]
Operations may be performed through the REST web service API or a language-specific AP.
(For information about the Rackspace language-specific APIs, see Rackspace Cloud SDKs
Software Development Kit Guide.)
7
Developer Guide
Important
All operations must include a valid authorization token.
2.7. CDN-enabled Containers
CDN-enabled containers serve content through Akamai's content delivery network (CDN).
CDN-enabled containers are publicly accessible for read access, so they do not require an
authorization token for read access. However, uploading content into a CDN-enabled
container is a secure operation and requires a valid authentication token.
Each CDN-enabled container has a unique URL that can be combined with its object names
and openly distributed in web pages, emails, or other applications.
For example, a CDN-enabled container named photos might be referenced as

http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com. If that container houses a screenshot called
wow1.jpg, that image can be served by a CDN with the full URL of
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.
rackcdn.com/wow1.jpg.
This URL can be embedded in items like HTML pages, email messages, or blog posts.
The first time that URL is accessed, a copy of that image is fetched from the Cloud Files
storage system. The copy is cached in a CDN and served from there for all subsequent
requests for a configurable cache time to live (TTL) value. Setting the TTL of a CDN-enabled
container translates to setting the Expires and Cache-Control HTTP headers. Note
that extremely long TTL values do not guarantee that an object is served from a CDN edge
location. When the TTL expires, the CDN checks Cloud Files to ensure that it has the most
up-to-date content. A purge request forces the CDN to check with Cloud Files for the most
up-to-date version of the file.
Cloud Files continues to serve content through the CDN until it receives a delete request.
Note
For more information about TTL, including its default, minimum, and maximum
values, see Section 9.3, “CDN Object Services” [93].
Containers tracked in the CDN management service are completely separate and distinct
from the containers defined in the storage service. It is possible for a container to be CDN-
enabled even if it does not exist in the storage system. You might want the ability to pre-
generate CDN URLs before actually uploading content and this separation gives you that
ability.
However, for the content to be served from the CDN, the container names MUST match in
both the CDN management service and the storage service. For example, you could CDN-
enable a container called images and be assigned the CDN URL, but you also need to
create a container called images in the storage service.
8
Developer Guide
2.8. Language-Specific APIs
Language-specific APIs in several popular languages are available to help put Cloud Files in
the hands of developers. These language-specific APIs provide a layer of abstraction on top
of the base REST API, allowing programmers to work with a container and object model
instead of working directly with HTTP requests and responses. The language-specific APIs
are free to download, use, and modify. They are licensed under the MIT license as described
in the COPYING file packaged with each API. If you make any improvements to an API, you
are encouraged (but not required) to submit those changes back to Rackspace.
Detailed information about the language-specific APIs is in the Rackspace Cloud SDKs
Software Development Kit Guide. If you have changes that you would like to see in the
Cloud File language-specific APIs, email them to [email protected]. Make sure to
indicate which language and version you modified and send a unified diff.
Each language-specific API has its own documentation (in HTML, PDF, or CHM format)
including code snippets and examples to help you get started.
You are welcome to create your own language-specific APIs. Rackspace will help answer
any questions during development, host your code if you like, and give you full credit for
your work.
9
Developer Guide
3. General API Information

The information in this chapter is relevant to all Cloud Files API operations. For information
about a specific API operation, see later chapters.
3.1. Authentication
Every REST request against the Cloud Files service requires the inclusion of a specific
authorization token, supplied by the X-Auth-Token HTTP header. Customers obtain this
token by first using the Rackspace Cloud Authentication Service and supplying a valid user
name and API access key.
3.1.1. Geographic Endpoints
The Rackspace Cloud Authentication Service serves as the entry point to all Rackspace
Cloud APIs and is itself a RESTful web service.
You can use either of the following endpoints to access the Authentication Service,
regardless of US or UK identities:
• https://identity.api.rackspacecloud.com/v2.0/.
• https://lon.identity.api.rackspacecloud.com/v2.0/.
Your account may be based in either the US or the UK. This is not determined by your
physical location but by the location of the Rackspace retail site that was used to create
your account.
• If your account was created via http://www.rackspacecloud.com, it is a US-based

account.
• If your account was created via http://www.rackspace.co.uk, it is a UK-based account.
If you are unsure how your account was created, use the Rackspace contact information at
either site to ask for help.
3.1.2. Retrieving the Authentication Token

POST v2.0/tokens Authenticate to receive a token and a service catalog.
Normal Status Code(s): 200, 203
Error Status Code(s): unauthorized (401), userDisabled (403), badRequest (400), authFault
(500), serviceUnavailable (503)
The authenticate operation provides clients with an authentication token and a list of
regional cloud endpoints. The sample requests and responses in this section illustrate
a general case. In your authentication request, use your own credentials rather than
the sample values shown here for username and apiKey. When you authenticate
successfully, the response to your authentication request will include a catalog of the
services to which you have subscribed rather than the sample values shown here.
Example 3.1. Auth Request: XML
10
Developer Guide
POST /v2.0/tokens HTTP/1.1

User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o
zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6
Host: identity.api.rackspacecloud.com
Accept: application/xml
Content-Type: application/xml
Content-Length: 88
<?xml version="1.0" encoding="UTF-8"?>

<auth>
<apiKeyCredentials
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
username= "jsmith"
apiKey= "aaaaa-bbbbb-ccccc-12345678"/>
</auth>
Example 3.2. Auth Request: JSON
POST /v2.0/tokens HTTP/1.1

User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o
zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6
Host: identity.api.rackspacecloud.com
Accept: application/json
Content-Type: application/json
Content-Length: 54
{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username": "jsmith",
"apiKey": "aaaaa-bbbbb-ccccc-12345678"
}
}
}
The username supplied here is your common Rackspace Cloud username.

The key is your API access key.
To find your API Key:
1. Log in to the Cloud Control Panel (https://mycloud.rackspace.com).
2. On the upper-right side of the top navigation pane, click your username.
3. From the menu, select Account Settings.
4. In the Login Details section of the Account Settings page, locate the API Key field
and click Show.
5. Copy the value of the API Key and paste it into a text editor of your choice.
11
Developer Guide
6. Click Hide to hide the value of the API Key.
You also need your cloud account number. In the documentation, the account
number is often referred to as your tenant name or tenant ID (technically, the ID is
different from the name, but at Rackspace, they are the same thing). Together, three
components—your username, your API Key, and your tenant ID or cloud account
number—form the authentication credentials that are required to connect to the
Rackspace cloud.
To find your tenant ID or cloud account number, locate your username on the upper-
right side of the top navigation pane in the Cloud Control Panel. The tenant ID or
account number is in parentheses just to the right of your username.
Note
For Cloud Files, the information used in place of the account number with
the API operations is the MossoCloudFS_aaaaaaaa-bbbb-cccc-
dddd-eeeeeeeeeeee information found in service catalog of your
authentication response, rather than the account number found in the
Cloud Control Panel, as described above.
Example 3.3. Auth Response: XML

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:50:20 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<access xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/
v1.0"
xmlns="http://docs.openstack.org/identity/api/v2.0"
xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
xmlns:common="http://docs.openstack.org/common/api/v1.0"
xmlns:ksgrp="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
xmlns:rax-kscatalog="http://docs.openstack.org/identity/api/ext/OS-
KSCATALOG/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<token id="vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz" expires=
"2011-12-08T22:51:02.000-06:00"/>
<user id="123456" name="jsmith" rax-auth:defaultRegion="DFW">
<roles>
<role id="identity:admin" name="identity:admin" description="Admin Role.
"/>
<role id="identity:default" name="identity:default" description="Default
Role."/>
</roles>
</user>
<serviceCatalog>
<service type="rax:database" name="cloudDatabases">
<endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.
databases.api.rackspacecloud.com/v1.0/1100111"/>
<endpoint region="ORD" tenantId="1100111" publicURL="https://ord.
databases.api.rackspacecloud.com/v1.0/1100111"/>
12
Developer Guide
</service>
<service type="rax:load-balancer" name="cloudLoadBalancers">
<endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.
loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
<endpoint region="ORD" tenantId="1100111" publicURL="https://ord.
loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
</service>
<service type="compute" name="cloudServersOpenStack">
<endpoint region="DFW" tenantId="1100111"
publicURL="https://dfw.servers.api.rackspacecloud.com/v2/1100111">
<version id="2" info="https://dfw.servers.api.rackspacecloud.com/v2/"
list="https://dfw.servers.api.rackspacecloud.com/" />
</endpoint>
<endpoint region="ORD" tenantId="1100111"
publicURL="https://ord.servers.api.rackspacecloud.com/v2/1100111">
<version id="2" info="https://ord.servers.api.rackspacecloud.com/v2/"
list="https://ord.servers.api.rackspacecloud.com/" />
</endpoint>
</service>
<service type="compute" name="cloudServers">
<endpoint tenantId="1100111"
publicURL="https://servers.api.rackspacecloud.com/v1.0/1100111">
<version id="1.0"
info="https://servers.api.rackspacecloud.com/v1.0/"
list="https://servers.api.rackspacecloud.com/"/>
</endpoint>
</service>
<service type="object-store" name="cloudFiles">
<endpoint region="DFW"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeee eee"
publicURL="https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
internalURL="https://snet-storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"/>
</service>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
cccc-dddd-eeeeeeeeeeee"/>
<endpoint region="ORD"
publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
cccc-dddd-eeeeeeeeeeee"/>
</service>
<service type="rax:dns" name="cloudDNS">
<endpoint tenantId="1100111"
publicURL="https://dns.api.rackspacecloud.com/v1.0/1100111"/>
</service>
</serviceCatalog>
</access>
13
Developer Guide
Example 3.4. Auth Response: JSON

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:45:13 GMT
{
"access": {
"token": {
"expires": "2011-12-08T22:51:02.000-06:00",
"id": "vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz"
},
"user": {
"id": "123456",
"name": "jsmith",
"RAX-AUTH:defaultRegion": "DFW",
"roles": [
{
"description": "Admin Role.",
"id": "identity:admin",
"name": "identity:admin"
},
{
"description": "Default Role.",
"id": "identity:default",
"name": "identity:default"
}
]
},
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://dfw.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.databases.api.
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudDatabases",
"type": "rax:database"
},
{
"endpoints": [
{
"publicURL": "https://dfw.loadbalancers.api.
"region": "DFW",
"tenantId": "1100111"
},
{
14
Developer Guide
"publicURL": "https://ord.loadbalancers.api.
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudLoadBalancers",
"type": "rax:load-balancer"
},
{
"endpoints": [
{
"tenantId": "1100111",
"region": "DFW",
"publicURL": "https://dfw.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://dfw.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://dfw.servers.api.
rackspacecloud.com/"
},
{
"tenantId": "1100111",
"region": "ORD",
"publicURL": "https://ord.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://ord.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://ord.servers.api.
rackspacecloud.com/"
}
],
"name": "cloudServersOpenStack",
"type": "compute"
},
{
"endpoints": [
{
"tenantId": "1100111",
"publicURL": "https://servers.api.rackspacecloud.com/
v1.0/1100111",
"versionId": "1.0",
"versionInfo": "https://servers.api.rackspacecloud.
com/v1.0/",
"versionList": "https://servers.api.rackspacecloud.
com/"
}
],
"name": "cloudServers",
"type": "compute"
},
{
"endpoints": [
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-
eeeeeeeeeeee",
"publicURL": "https://storage101.dfw1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
15
Developer Guide
"internalURL": "https://snet-storage101.dfw1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "DFW"
},
{
eeeeeeeeeeee",
"publicURL": "https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"internalURL": "https://snet-storage101.ord1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "ORD"
}
],
"name": "cloudFiles",
"type": "object-store"
},
{
"endpoints": [
{
eeeeeeeeeeee",
"publicURL": "https://cdn1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "DFW"
},
{
eeeeeeeeeeee",
"publicURL": "https://cdn2.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "ORD"
}
],
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"tenantId": "1100111",
"publicURL": "https://dns.api.rackspacecloud.com/v1.0/
1100111"
}
],
"name": "cloudDNS",
"type": "rax:dns"
}
]
}
}
Note
The information shown in the Auth Response examples is for US-based
accounts. If you authenticate against the UK-endpoint for auth, you will see the
service catalog information for UK-based accounts.
16
Developer Guide
In XML responses only, a list of namespaces identifies API extensions that add
functionality to the core API.
This token can be presented to a service as evidence of authentication. Tokens are

valid for a finite duration. A token's default lifespan is twenty-four hours.
The token's expires attribute denotes the time after which the token will
automatically become invalid. A token may be manually revoked before the time
identified by the expires attribute. The expires attribute predicts a token's
maximum possible lifespan but does not guarantee that it will reach that lifespan.
Clients are encouraged to cache a token until it expires.
Users can be assigned a default region so that, when there is a choice between
multiple endpoints associated with a service in the user's catalog, the endpoint for the
user's default region will be selected if it is available. In this example, the user's default
region is DFW and several of the services in the catalog offer endpoints in that region
and the ORD region. The user's work will be directed to the DFW region whenever
possible.
Users can be assigned multiple roles, with each role providing specific privileges.
In this example, jsmith is the administrative user for the account, holding the
fully-privileged identity:admin role. Other users might hold other roles with
different privileges. Roles need not be associated with actual job functions such as
Administrator, Operator, Developer, Tester, or Trainer.
The service catalog lists the services you can access. In this example, the user can access
one database service, one loadbalancing service, two compute services (Cloud Servers
OpenStack and Cloud Servers), two object storage services (Cloud Files Content
Distribution Network (CDN), and Cloud Files), and one DNS service. The catalog
listing for each service provides at least one endpoint URL for that service. Other
information, such as regions, versions, and tenants, is provided if it's relevant to this
user's access to this service.
The service type attribute identifies services that perform similar functions, whatever
those services might be named. In this example, the services named cloudServers and
cloudServersOpenstack are both identified as type="compute", identifying them as
compute services even though the word "compute" does not appear in their names.
Important
Use service type as the primary value for locating a service. If multiple
endpoints of the same service type exist in the same region, use service
name as the tiebreaker.
The service name attribute identifies each unique service in the catalog. Once a service
is created, its name does not change. However, new services of the same service type
may be added to the catalog with new names.
Important
If you are programmatically parsing an authentication response, use
service type rather than service name as the basis for determining whether
17
Developer Guide
a user has access to a particular kind of service. Service type is stable across
all releases. New service types may be developed, but existing service types
are not renamed. In this example, type="compute" identifies all the
available compute services, one of which is named cloudServers and one of
which is named cloudServersOpenStack. New compute service names may
be added in future releases. Whatever the compute services are named,
you can always recognize them by parsing for type="compute" in the
authentication response's service catalog.
A service may expose endpoints in different regions. Regional endpoints allow clients
to provision resources in a manner that provides high availability.
Some services are not region-specific. These services supply a single non-regional
endpoint and do not provide access to internal URLs.
Some services recognize specification of a tenant. If a service does recognize tenants,

the format of the tenant specification is defined only by the service. For details about
whether and how to specify a tenant, check the documentation for the service you are
using.
An endpoint can be assigned public and internal URLs. A public URL is accessible from
anywhere. Access to a public URL usually incurs traffic charges. Internal URLs are
only accessible to services within the same region. Access to an internal URL is free of
charge.
Authentication tokens are typically valid for 24 hours. Applications should be designed to
re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.
Important
If you are programmatically parsing an authentication response, please be
aware that service names are stable for the life of the particular service and
can be used as keys. You should also be aware that a user's service catalog can
include multiple uniquely-named services which perform similar functions. For
example, cloudServersOpenStack is the OpenStack version of compute whereas
cloudServers is the legacy version of compute. The same user can have access
to both services. In Auth 2.0, the service type attribute can be used as a key by
which to recognize similar services.
Tip
Beginning with Auth 2.0, the service catalog includes a service type attribute to
identify services that perform similar functions but have different names. For
example, type="compute" identifies compute services such as cloudServers
and cloudServersOpenStack. Some developers have found the service type
attribute to be useful in parsing the service catalog. For additional information
on Auth 2.0 (also known as the Cloud Identity Service), refer to the Cloud
Identity Client Developer Guide at http://docs.rackspace.com/.
Cloud Files service endpoints are published in the service catalog in the Auth response
with the account information, which is a required element of the service endpoints. The
examples shown here are for authentication for US customers. Customers with UK-based
18
Developer Guide
accounts will see different values in the service catalog. Refer to Section 3.3, “Service Access
Endpoints” [20] for more information about service endpoints.
3.2. Role Based Access Control

Role Based Access Control (RBAC) restricts access to the capabilities of Rackspace Cloud
services, including the Cloud Files API, to authorized users only. RBAC enables Rackspace
Cloud customers to specify which account users of their Cloud account have access to which
Cloud Files API service capabilities, based on roles defined by Rackspace (see Table 3.1,
“Cloud Files Product Roles and Permissions” [19]). The permissions to perform certain
operations in the Cloud Files API – create, read, update, delete – are assigned to specific
roles, and these roles can be assigned by the Cloud account admin user to account users of
the account.
3.2.1. Assigning Roles to Account Users

The account owner (identity:user-admin) can create account users on the account and
then assign roles to those users. The roles grant the account users specific permissions for
accessing the capabilities of the Cloud Files service. Each account has only one account
owner, and that role is assigned by default to any Rackspace Cloud account when the
account is created.
See the Cloud Identity Client Developer Guide for information about how to perform the
following tasks:
• Create account users
• Assign roles to account users
• Delete roles from account users
Note
The account owner (identity:user-admin) role cannot hold any additional roles
because it already has full access to all capabilities.
3.2.2. Roles Available for Cloud Files

Two roles (admin and observer) can be used to access the Cloud Files API specifically. The
following table describes these roles and their permissions.
Table 3.1. Cloud Files Product Roles and Permissions

Role Name Role Permissions
object-store:admin This role provides Create, Read, Update, and Delete
permissions in Cloud Files, where access is granted.
object-store:observer This role provides Read permission in Cloud Files, where
access is granted.
Additionally, two multiproduct roles apply to all products. Users with multiproduct
roles inherit access to future products when those products become RBAC-enabled. The
following table describes these roles and their permissions.
19
Developer Guide
Table 3.2. Multiproduct (Global) Roles and Permissions

Role Name Role Permissions
admin This role provides Create, Read, Update, and Delete permissions in all
products, where access is granted.
observer This role provides Read permission in all products, where access is granted.
3.2.3. Resolving Conflicts Between RBAC Multiproduct vs.

Custom (Product-specific) Roles
The account owner can set roles for both multiproduct and Cloud Files scope, and it is
important to understand how any potential conflicts among these roles are resolved. When
two roles appear to conflict, the role that provides the more extensive permissions takes
precedence. Therefore, admin roles take precedence over observer and creator roles,
because admin roles provide more permissions.
The following table shows two examples of how potential conflicts between user roles in
the Control Panel are resolved:
Permission Configuration View of Permission Can the User Perform Product Admin
in the Control Panel Functions in the Control Panel?
User is assigned the following roles: Appears that the user has only the Yes, for Cloud Files only. The user has
multiproduct observer and Cloud Files multiproduct observer role the observer role for the rest of the
admin products.
User is assigned the following roles: Appears that the user has only the Yes, for all of the products. The Cloud
multiproduct admin and Cloud Files multiproduct admin role Files observer role is ignored.
observer
3.2.4. RBAC Permissions Cross-reference to Cloud Files API

Operations
API operations for Cloud Files may or may not be available to all roles. To see which
operations are permitted to invoke which calls, please review the Knowledge Center article.
3.3. Service Access Endpoints

Cloud Files is a regionalized service. You can create your Cloud Files containers in any
Rackspace data center. The user of the service is therefore responsible for appropriate
replication, caching, and overall maintenance of Cloud Files data across regional boundaries
to other Cloud Files servers.
The endpoints to use for the storage service component of your Cloud Files API calls are
summarized in the table below.
Table 3.3. Regionalized Service Endpoints for Storage Services

Region Endpoint
Chicago (ORD) https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.ord1.clouddrive.com/
Dallas/Ft. Worth (DFW) https://storage101.dfw1.clouddrive.com/
20
Developer Guide
Region Endpoint
https://snet-storage101.dfw1.clouddrive.com/
Hong Kong (HKG) https://storage101.hkg1.clouddrive.com/
https://snet-storage101.hkg1.clouddrive.com/
London (LON) https://storage101.lon3.clouddrive.com/
https://snet-storage101.lon3.clouddrive.com/
Northern Virginia (IAD) https://storage101.iad3.clouddrive.com/
https://snet-storage101.iad3.clouddrive.com/
Sydney (SYD) https://storage101.syd2.clouddrive.com/
https://snet-storage101.syd2.clouddrive.com/
Replace the sample MossoCloudFS information in the table above with the actual
MossoCloudFS information returned as part of the authentication service response. You
will find this after the final '/' in the publicURL field and the internalURL field in the
cloudFiles section of the service catalog returned by the authentication response. For
more information about the account number, see the sample authentication request and
response in Section 3.1.2, “Retrieving the Authentication Token” [10] as well as the
Cloud Identity Client Developer Guide.
Tip
If you do not know which data center you are working in or your account ID,
you can find them in your Cloud Control Panel at mycloud.rackspace.com.
If you are working with cloud servers that are in one of the Rackspace data centers, using
the ServiceNet endpoint in the same data center has no network costs and provides a faster
connection. ServiceNet endpoints are prefixed with snet- in Table 3.3, “Regionalized
Service Endpoints for Storage Services ” [20]. ServiceNet is the data center internet
network. In your authentication response, it is listed as internalURL.
If you are working with servers that are not in one of the Rackspace data centers, you must
use a public endpoint to connect. In your authentication response, public endpoints are
listed as publicURL. If you are working with servers in multiple data centers or have a
mixed environment where you have servers in your data centers and in Rackspace data
centers, use a public endpoint because it is accessible from all the servers in the different
environments.
Note
In order to avoid external bandwidth charges, your containers and servers must
be in the same data center.
You might find it useful to locate your objects in more than one data center to
keep track of your data and backups. Specifically, if you serve an audience in a
21
Developer Guide
particular region, you might find it helpful to locate your Cloud Files objects as
close to that region as possible.
The endpoints to use for the CDN management service component of your Cloud Files API
calls are summarized in the table below.
Note
If your audience is world wide, you might consider using the Akamai Content
Delivery Network (CDN). The CDN speeds your content delivery because it is
cached at edge locations around the globe, rather than being served from a
single origin server. You can learn more about CDN-enabling your containers in
Section 9.2.1, “CDN-Enable and CDN-Disable a Container” [86].
Table 3.4. Regionalized Service Endpoints for CDN Management Services

Region Endpoint
Chicago (ORD) https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
cccc-dddd-eeeeeeeeeeee/
Dallas/Ft. Worth (DFW) https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
Hong Kong (HKG) https://cdn6.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
London (LON) https://cdn3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
Northern Virginia (IAD) https://cdn5.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
Sydney (SYD) https://cdn4.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
As with the storage component service, replace the sample MossoCloudFS information
with the actual MossoCloudFS information returned as part of the authentication service
response. For the CDN management service, you will find this information after the final '/'
in the publicURL field in the cloudFilesCDN section of the service catalog returned by
the authentication response.
3.4. Cloud Files Service Contract Version

The Cloud Files version defines the contract and build information for the API.
The contract version denotes the data model and behavior that the API supports. The
requested contract version is included in all request URIs. Different contract versions of the
API may be available at any given time and are not guaranteed to be compatible with one
another.
Example 3.5. Example Request URL (contract version in bold)

https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-
dddd-eeeeeeeeeeee
Note
This document pertains to contract version 1.
22
Developer Guide
3.5. Absolute Limits
Absolute limits are fixed. Absolute limits control the total number of specific objects that
the user can have or process in Cloud Files.
Refer to the following table for the absolute limits.
Table 3.5. Absolute Limits
Name Description Limit
Containers per account Maximum number of containers per account 500,000 containers
Container listing Maximum number of containers that can be listed at 10,000 containers
one time
Pseudo hierarchical folders and Simulated hierarchical structure within a single No limit
directories container by adding forward slash characters (/) in
the object name
Container and object metadata Maximum metadata limits 4096 bytes maximum overall
limits metadata, with 90 distinct
metadata items at the
most. Each may have a 128
character name length with
a 256 max value length
each.
Number of object segments per Maximum number of object segments per SLO 1,000 object segments
Static Large Object (SLO)
TTL for a CDN-enabled container Maximum TTL for a CDN-enabled container 1 year -31536000 seconds
Container name length Maximum length of container name 256 bytes
Object name length Maximum length of object name 1024 bytes
Upload limit for a request Maximum object size for an upload in a single 5 GB (For larger files, see
request Section 8.2.2, “Static Large
Object Creation” [74])
or Section 8.2.1,
“Dynamic Large Object
Creation” [72].)
CDN file size limit Maximum size of file that can be served from CDN 10 GB
Rate limit for write operations Maximum number of write operations per second 100 operations per second
per container, where a write operation is a COPY,
DELETE, POST, or PUT. If you reach this rate limit,
Cloud Files slows the processing of write requests for
the container to 100 operations per second.
3.6. Request and Response Types

You specify the request format using the Content-Type header. The Cloud Files API
supports both the JSON (application/json) and XML (application/xml) data
serialization formats, as well as other formats such as text/plain, text/xml, and
text/html along with video, audio, and image types. For pseudo hierarchical folders
and directories, application/directory might be used.
You specify the response format in requests by using the Accept header. The Cloud Files
API supports both the JSON (application/json) and XML (application/xml) data
serialization formats, as well as other formats such as text/plain and text/xml .
23
Developer Guide
4. Overview of API Operations

The Cloud Files API is implemented as a set of RESTful web services. All authentication
and container/object operations can be performed with standard HTTP calls. For more
information about REST, see Representation State Transfer.
The following constraints apply to REST API HTTP requests:
• Maximum number of HTTP headers per request: 90
• Maximum length of all HTTP headers: 4096 bytes
• Maximum length per HTTP request line: 8192 bytes
• Maximum length of HTTP request: 5 gigabytes
• Maximum length of container name: 256 bytes
• Maximum length of object name: 1024 bytes
Container and object names must be UTF-8 encoded and then should be properly URL-
encoded prior to interacting with the REST interface. You might be using an API binding
that performs the URL-encoding on your behalf. If so, do not URL-encode before calling the
API binding, or you will double-encode container and object names. The length restrictions
should be checked against the URL-encoded string.
Note
The language-specific APIs handle URL-encoding and decoding.
Each REST request against Cloud Files requires the inclusion of an authorization token in
the HTTP header X-Auth-Token. Clients obtain this token, along with the Cloud Files
URIs, by first using the Rackspace authentication service and supplying a valid user name
and API access key. For more information, see Section 3.1, “Authentication” [10].
The two sets of REST services that make up the full Cloud Files product are:
• Storage Service: The REST service identified with cloudFiles in the service catalog (see
Section 3.1.2, “Retrieving the Authentication Token” [10]) manages the data storage in
the system. Example operations are creating containers and uploading objects.
• CDN Service: The REST service identified with cloudFilesCDN in the service catalog
(see Section 3.1.2, “Retrieving the Authentication Token” [10]) manages the CDN feature
of Cloud Files.
24
Developer Guide
In the following sections, the purpose of each HTTP method depends upon which service
the call is made against. For example, a PUT request against one of the cloudFiles
endpoints can be used to create a container or upload an object, while a PUT request
against the one of the cloufFilesCDN endpoints is used to CDN-enable a container.
The language-specific APIs mask this system separation from the programmer. They simply
create a container and mark it public and handle calling the appropriate back-end services
by using the appropriate REST APIs.
Note
All requests to authenticate and operate against Cloud Files are performed
using SSL over HTTP (HTTPS) on TCP port 443.
The following diagram illustrates the various system interfaces and the ease with which
content can be distributed over the CDN. The process is simple: authenticate, create a
container, upload objects, mark the container as public, and begin serving that content
from a powerful CDN.
Note
Marking the container as public simply means enabling the container to be
distributed over the CDN. A CDN-enabled container is publicly accessible.
Figure 4.1. Cloud Files System Interfaces
1 . Au t h e n t ica t e
2 . Cr e a t e Con t a in e r
Ra ck sp a ce Clou d a n d Up loa d Ob je ct s
Au t h e n t ica t ion
Se r vice
4 . Se r ve Con t e n t
3 . M a r k Con t a in e r s Pu b lic
CD N M a n a g e m e n t St or a g e
Se r vice Se r vice
25
Developer Guide
5. API Operations for Storage Services

This chapter describes each of the API operations provided by the Cloud Files service.
All requests are directed to the endpoints described in the cloudFiles section of the
service catalog obtained during successful authentication. (For more information, see
Section 3.1, “Authentication” [10] and Section 3.3, “Service Access Endpoints” [20].)
Following are some requirements for the storage services component:
• Object and container names must be URL-encoded and UTF-8 encoded.
• Container names may not exceed 256 bytes and cannot contain a '/' character.
• Object names may not exceed 1024 bytes, but they have no character restrictions.
The following sections describe the operations that you can perform within the storage
system:
• Section 5.1, “Account Services” [27] describes operations that you can perform at the
account level of the storage system.
• Section 5.2, “Container Services” [36] describes operations that you can perform on
containers.
• Section 5.3, “Object Services” [50] describes operations that you can perform on
objects.
Method URI Description

Account Services
GET v1/{account}{?limit,marker, Lists storage containers sorted by name.
end_marker,format}
POST v1/{account} Creates or updates account metadata.
HEAD v1/{account} Gets account metadata.
POST v1/{account} Deletes account metadata.
Container Services
GET v1/{account}/{container}{?limit, Lists the objects stored in the container.
marker,end_marker,prefix,format,
delimiter,path}
PUT v1/{account}/{container} Creates a container.
DELETE v1/{account}/{container} Deletes an empty container.
POST v1/{account}/{container} Creates or updates the container metadata by associating
custom metadata headers with the container level URI.
These headers must have the format, X-Container-Meta-
name.
HEAD v1/{account}/{container} Gets container metadata, including the number of objects
in the container and the total bytes for all objects stored in
the container.
POST v1/{account}/{container} Deletes container metadata.
Object Services
GET v1/{account}/{container}/{object} Gets data for the specified object.
PUT v1/{account}/{container}/{object} Creates or updates the content and metadata for a
specified object.
26
Developer Guide

DELETE v1/{account}/{container}/{object} Permanently deletes an object from the Cloud Files
storage system. (You can use COPY and then DELETE to
effectively move an object.)
COPY v1/{account}/{container}/{object} Using the Destination header, copies an existing object to
another object with a new name in the Cloud Files storage
system.
HEAD v1/{account}/{container}/{object} Gets object metadata and other standard HTTP headers.
POST v1/{account}/{container}/{object} Sets or updates your object metadata. Metadata must
be in the format X-Object-Meta- name, where name
is the name of your metadaa. You can also assign X-
Delete-At or X-Delete-After to expiring objects.
You cannot use this operation to change other headers,
such as Content-Type.
5.1. Account Services
You can perform the operations in the following table at the account level of your Cloud
Files account.
The examples in this section use sample information for:
• account, such as MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123
• X-Auth-Token, such as f064c46a782c444cb4ba4b6434288f7c
For your own requests, you must use your own account information and authentication
token. You can check how to generate an authentication token in Section 3.1.2,
“Retrieving the Authentication Token” [10]. Your authentication token and your account
information are in the service catalog that is produced.

end_marker,format}
27
Developer Guide
5.1.1. List Account Containers

end_marker,format}
This operation lists the storage containers in your account and sorts them by name.
The container is the basic storage unit in Cloud Files. To view a list of the containers in your
account, perform a GET operation against your storage account URL.
The list is limited to 10,000 containers at a time. See "Controlling a Large List of Containers"
below for information on limiting and navigating the list.
Container names are sorted based on a binary comparison ( http://www.sqlite.org/

datatype3.html#collation), a built-in collating function that compares string data using
SQLite's memcmp() function, regardless of text encoding.
A list of containers is returned in the response body, one container per line.
The character sequence used to create the newline that separates the container
names is a single \n. If you want to parse these listings, you should send an Accept:
application/json or Accept: application/xml header with the request to get
the results in JSON or XML.
The HTTP response status code is a value from 200 to 299, inclusive. A 200 (OK) code
returns if there are containers, and a 204 (No Content) code returns if there are no
containers.
Format Container List
If you append the ?format=xml or ?format=json query parameter to the storage

account URL, the service returns container information serialized in the specified format. To
format your results, you must place this query parameter before any other parameters.
The example responses below are formatted for readability.
Controlling a Large List of Containers
A GET operation on the storage account URL returns a list of up to 10,000 container
names. You can control and limit this list of results by using the marker, end_marker, and
limit parameters. These parameters provide a mechanism to iterate through the entire
list of containers.
The marker parameter tells Cloud Files where to begin your list of containers and
end_marker specifies where to end the list. You can use them independently or together,
separated by an ampersand (&). If you do not specify them, your list displays up to 10,000
containers. Note that the marker and end_marker values should be URL-encoded prior
to sending the HTTP request.
You can use the limit parameter to reduce the number of returned objects.
28
Developer Guide
If the number of returned items equals the limit used (or 10,000 if no limit was
specified), you can assume there are more object names.
Note
At this time, a prefix query parameter is not supported at the account level.
As an example, start with an account that has five container names, as follows:
apples
bananas
kiwis
oranges
pears
Use a limit of 2 to show how things work:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
apples
bananas
Because the operation returned two items, assume there are more container names to list
and make another request with a marker of the last item returned:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=
bananas
kiwis
oranges
Again, two items are returned, and you assume that there may be more. So you make
another GET request for two more.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=
oranges
pears
This one-item response shows less than the limit of 2 container names requested, and
indicates that this is the end of the list.
By using end_marker, you can limit the result set to container names less than the given
value.
29
Developer Guide
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?end_marker=oranges
apples
bananas
kiwis
Normal response codes: 200, 204
5.1.1.1. Request
This table shows the URI parameters for the List Account Containers Request:
Name Type Description

{account} String Your unique account identifier.
This table shows the Query parameters for the List Account Containers Request:

limit Int For an integer value n, limits the number of results to n values.
(Optional)
marker String Given a string value x, returns container names greater in value than
the specified marker. Only strings using UTF-8 encoding are valid.
(Optional)
end_marker String Given a string value x, returns container names less in value than the
specified marker. Only strings using UTF-8 encoding are valid.
(Optional)
format String Value of the serialized response format - either json or xml.
(Optional)
Example 5.1. List Account Containers Request: XML

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=xml HTTP/1.1
Content-Length: 0
X-Storage-Token: f064c46a782c444cb4ba4b6434288f7c}
Example 5.2. List Account Containers Request: JSON

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=json HTTP/1.1
Content-Length: 0
X-Storage-Token: f064c46a782c444cb4ba4b6434288f7c}
5.1.1.2. Response
This table shows the Body parameters for the List Account Containers Response:

name String Name of the container.
(Required)
30
Developer Guide

count Int Number of objects in the container.
(Required)
bytes Int Number of bytes in the container.
(Required)
Example 5.3. List Account Containers Response: XML

HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:42:35 GMT
Content-Type: application/xml; charset=utf-8
<account name="name">
<container>
<name>test_container_1</name>
<count>2</count>
<bytes>78</bytes>
</container>
<container>
<name>test_container_2</name>
<count>1</count>
<bytes>17</bytes>
</container>
</account>
Example 5.4. List Account Containers Response: JSON

HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:39:13 GMT
Content-Type: application/json; charset=utf-8
[
{"name":"test_container_1", "count":2, "bytes":78},
{"name":"test_container_2", "count":1, "bytes":17}
]
31
Developer Guide
5.1.2. Create or Update Account Metadata

You can associate custom metadata headers with the account level URI. To create or
update an account metadata header, submit a POST operation. These headers must have
the format X-Account-Meta-name. Replace name with name of your metadata. (In
the example request below, the metadata headers are X-Account-Meta-Book and X-
Account_Meta-Subject.)
Subsequent POST operations for the same key/value pair overwrite the previous value.
A status code of 2xx (between 200 and 299, inclusive) indicates success.
This operation does not require a request body and does not return a response body.
To confirm your metadata changes, you can perform a HEAD operation on the account.
(For information, see Section 5.1.3, “Get Account Metadata” [34].) Do not send the
metadata in your HEAD operation.
Normal response codes: 204
5.1.2.1. Request
This table shows the Header parameters for the Create or Update Account Metadata
Request:

X-Account-Meta-name String Header for the account metadata that you want to create or update.
Replace the name at the end of the header with the name for your
(Required) metadata.
This table shows the URI parameters for the Create or Update Account Metadata Request:

Example 5.5. Create or Update Account Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1
X-Account-Meta-Book: MobyDick
X-Account-Meta-Subject: Whaling
5.1.2.2. Response
Example 5.6. Create or Update Account Metadata Response
HTTP/1.1 204 No Content
Content-Length: 0
32
Developer Guide
Content-Type: text/html; charset=UTF-8

X-Trans-Id: tx1b4be419af2c4d688ee4d-0052cf1ea4dfw1
Date: Thu, 09 Jan 2014 22:11:48 GMT
33
Developer Guide
5.1.3. Get Account Metadata

Perform a HEAD operation on your storage account URL to get the following information:
• How many objects are in your account (X-Account-Object-Count)

• How many total bytes your account uses (X-Account-Bytes-Used)
• How many containers you have in your account (X-Account-Container-Count)
The HTTP return code is 2xx (between 200 and 299, inclusive) if the request succeeds. In
the example, a 204 (No Content) code is returned. A 401 (Unauthorized) is returned for an
invalid account or authentication token.
Error response codes: unauthorized (401)
5.1.3.1. Request
This table shows the URI parameters for the Get Account Metadata Request:

Example 5.7. Get Account Metadata Request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1
5.1.3.2. Response
This table shows the Header parameters for the Get Account Metadata Response:

X-Account-Object-Count Int The total number of objects that are stored in Cloud Files for the
account.
(Required)
X-Account-Bytes-Used Int The total number of bytes that are stored in Cloud Files for the
account.
(Required)
X-Account-Container-Count Int The total number of containers that are stored in the Cloud Files for
the account.
(Required)
Example 5.8. Get Account Metadata Response

Content-Length: 0
34
Developer Guide
X-Account-Object-Count: 573
X-Timestamp: 1369081921.78518
X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284e
X-Account-Bytes-Used: 14268918
X-Account-Container-Count: 1
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx8e82a77399724e40a90e8-0052cf0e52dfw1
Date: Thu, 09 Jan 2014 21:02:10 GMT
35
Developer Guide
5.1.4. Delete Account Metadata

To delete a metadata header, use the POST operation to send an empty value for that
particular header.
If the tool you use to communicate with Cloud Files does not support empty headers, such
as an older version of cURL, send the X-Remove-Account-Meta-name: arbitrary
value header. The arbitrary value is ignored. In the example request below, X-
Remove-Account-Meta-Book: x is used.
A status code of 2xx (between 200 and 299, inclusive) indicates success.
5.1.4.1. Request
This table shows the Header parameters for the Delete Account Metadata Request:
X-Remove-Account-Meta- String Header to send to delete account metadata. Replace the name at the
name end of the header with the name for your metadata.
(Required)
This table shows the URI parameters for the Delete Account Metadata Request:
Example 5.9. Delete Account Metadata Request

X-Remove-Account-Meta-Book: x
5.1.4.2. Response
Example 5.10. Delete Account Metadata Response
Content-Length: 0
X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1
Date: Thu, 09 Jan 2014 22:28:22 GMT
5.2. Container Services
You can perform the operations in the following table on containers in your Cloud Files
account.
36
Developer Guide
• container, such as MyContainer
For your own requests, you must use your own account information, authentication
token, and container name. You can check how to generate an authentication token in
Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token and
your account information are in the service catalog that is produced.

delimiter,path}
name.
the container.
37
Developer Guide
5.2.1. List Container Objects

delimiter,path}
This operation against a storage container name retrieves a list of objects stored in the
container. Additionally, you can use optional query parameters to refine the list results.
A request with no query parameters returns the full list of object names stored in the
container, up to 10,000 names. The response body shows the object names as one object
name per line. Specifying the query parameters filters the full list and returns a subset of
objects. For information on limiting and controlling the list, see the following “Controlling a
Large List of Objects” section.
The HTTP response status code is a value from 200 to 299, inclusive. A status code of 200
(OK) is returned if there are objects, and a 204 (No Content) is returned if there are no
objects. If the container does not exist, or if an incorrect account is specified, a status code
404 (Not Found) is returned.
For information on filtering the results of a container list, see Chapter 6, “Pseudo
Hierarchical Folders and Directories” [66].
Format Object List
If you append the format=xml or the format=json query parameter to the storage
account URL, the service returns additional object information serialized in the specified
format. The status codes are the same when using format=xml or format=json.
However, Content-Type matches the specified format. The example responses below are
formatted for readability.
Controlling a Large List of Objects
A GET request against the container account URL returns a list of up to 10,000 objects. You
can limit and control this list of results by using the marker, end_marker, and limit
parameters.
The marker parameter tells Cloud Files where to begin your list of objects, and
end_marker tells where to end the list. You can use them either independently or
together, separated by an ampersand (&). If you do not specify them, your list displays up
to 10,000 objects. Note that the marker and end_marker values should be URL-encoded
prior to sending the HTTP request.
You can use the limit parameter to reduce the number of returned objects.
If the number of returned items equals the limit used (or 10,000 if no limit was
specified), you can assume there are more object names.
As an example, use a listing of 5 object names, as follows:
gala
38
Developer Guide
grannysmith
honeycrisp
jonagold
reddelicious
Use a limit of 2 to show how things work:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2
gala
grannysmith
Because the request returned two items, assume there are more object names to list and
make another request with a marker of the last item returned:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&
marker=grannysmith
honeycrisp
jonagold
Again, two items are returned, and you assume that there may be more. So you make
another GET request for two more.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&
marker=jonagold
reddelicious
This one-item response shows less than the limit of two object names requested, and
indicates that this is the end of the list.
Error response codes: itemNotFound (404), Conflict (409)
5.2.1.1. Request
This table shows the URI parameters for the List Container Objects Request:

{container} String The unique identifier of the container.
This table shows the Query parameters for the List Container Objects Request:
39
Developer Guide

limit Int For an integer n, limits the number of results to n values.
(Optional)
marker String Given a string value x, returns object names greater in value than the
specified marker.
(Optional)
end_marker String Given a string value x, returns object names less in value than the
specified marker.
(Optional)
prefix String For a string value x, causes the results to be limited to object names
beginning with the substring x.
(Optional)
format String Specifies either json or xml to return the respective serialized response.
(Optional)
delimiter Char For a character c, returns the object names nested in the container
(without the need for the directory marker objects).
(Optional)
path String For a string x, returns the object names nested in the pseudo path.
Equivalent to setting delimiter to '/' and prefix to the path with a '/' on
(Optional) the end. For more information about pseudo paths, see the section on
pseudo hierarchical folders and directories.
Example 5.11. List Container Objects Request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1
Example 5.12. List Container Objects Request: XML

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=xml HTTP/1.1
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4
Example 5.13. List Container Objects Request: JSON

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=json HTTP/1.1
Content-Length: 0
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4
5.2.1.2. Response
This table shows the Header parameters for the List Container Objects Response:

Last-Modified String An internal variable that indicates the last time an entity (account,
container, or object) was modified. Last-Modified has resolution up to
(Required) one second. For Last-Modified, the time zone is UTC.
Example 5.14. List Container Objects Response

HTTP/1.1 200 OK
Date: Thu, 07 Jun 2010 18:50:19 GMT
40
Developer Guide
Content-Type: text/plain; charset=UTF-8

Content-Length: 171
kate_beckinsale.jpg
How To Win Friends And Influence People.pdf
moms_birthday.jpg
poodle_strut.mov
Disturbed - Down With The Sickness.mp3
army_of_darkness.avi
the_mad.avi
Example 5.15. List Container Objects Response: XML

HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:42:35 GMT
Content-Length: 643
<container name="test_container_1">
<object>
<name>test_object_1</name>
<hash>4281c348eaf83e70ddce0e07221c3d28</hash>
<bytes>14</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2009-02-03T05:26:32.612278</last_modified>
</object>
<object>
<name>test_object_2</name>
<hash>b039efe731ad111bc1b0ef221c3849d0</hash>
<bytes>64</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2009-02-03T05:26:32.612278</last_modified>
</object>
</container>
Example 5.16. List Container Objects Response: JSON

HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:39:13 GMT
Content-Length: 387
[
{"name":"test_obj_1",
"hash":"4281c348eaf83e70ddce0e07221c3d28",
"bytes":14,
"content_type":"application\/octet-stream",
"last_modified":"2009-02-03T05:26:32.612278"},
{"name":"test_obj_2",
"hash":"b039efe731ad111bc1b0ef221c3849d0",
"bytes":64,
"content_type":"application\/octet-stream",
"last_modified":"2009-02-03T05:26:32.612278"}
]
41
Developer Guide
5.2.2. Create Container

This operation creates a Cloud Files container. Containers are storage compartments for
your data. The URL-encoded name must be less than 256 bytes and cannot contain a
forward slash character (/). You can create up to 500,000 containers in your Cloud Files
account.
You can assign custom metadata for containers by including additional HTTP headers with
an X-Container-Meta- prefix on the POST request. See Section 5.2.4, “Create or Update
Container Metadata” [45] for details on setting custom metadata.
Using custom container metadata, you can create information in the header to effectively
tag a container with metadata. The container metadata restrictions are the same as object
metadata. You can have 4096 bytes maximum of overall metadata, with a maximum of
90 distinct metadata items. Each can have a name length of up to 128 characters with a
maximum of 256 bytes in the value. Any valid UTF-8 encoded string value is allowed for
metadata. In addition for custom metadata, we recommend that you URL-encode any non-
ASCII values using a "%" symbol, followed by the two-digit hexadecimal ISO-Latin code for
the character.
A status code of 201 (Created) indicates that the container was created as requested.
Container PUT requests are idempotent, and a code of 202 (Accepted) is returned if the
container existed prior to the request. If you request a PUT to a container with an X-
Container-Meta- prefix in the header, your GET or HEAD request responses carry the
metadata prefix from the container in subsequent requests.
5.2.2.1. Request
This table shows the Header parameters for the Create Container Request:

X-Container-Meta-name String Custom container metadata. Replace the name at the end of the
header with the name for your metadata.
(Optional)
This table shows the URI parameters for the Create Container Request:

Example 5.17. Create Container Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1
42
Developer Guide
Example 5.18. Create Container with Metadata Request

X-Container-Meta-InspectedBy: JackWolf
5.2.2.2. Response
Example 5.19. Create Container Response
HTTP/1.1 201 Created
Date: Thu, 07 Jun 2007 18:50:19 GMT
Example 5.20. Create Container with Metadata Response

Date: Thu, 07 Jun 2010 18:50:19 GMT
43
Developer Guide
5.2.3. Delete Container

A DELETE operation against a storage container permanently removes it. The container
must be empty before it can be deleted.
Before using DELETE, you can use a GET operation against the container to list any objects
it contains. (See Section 5.2.1, “List Container Objects” [38].)
A status code of 204 (No Content) indicates success. A status code of 404 (Not Found) is
returned if the requested container is not found. A status code of 409 (Conflict) is returned
if the container is not empty.
Error response codes: itemNotFound (404), Conflict (409)
5.2.3.1. Request
This table shows the URI parameters for the Delete Container Request:

Example 5.21. Delete Container Request

DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
5.2.3.2. Response
Example 5.22. Delete Container Response
Date: Thu, 07 Jun 2007 18:57:07 GMT
Content-Length: 0
44
Developer Guide
5.2.4. Create or Update Container Metadata

name.
To set or edit container metadata, perform a POST operation to the container. The
operation must include X-Container-Meta-name, where name is the name of your
custom metadata. Subsequent POSTPOST to the header using the same metadata name
overwrite the previous value.
To view your metadata changes, perform a HEAD operation on the container. (For more
information, see Section 5.2.5, “Get Container Metadata” [47].) Do not try to send the
metadata in your HEAD request.
A status code of 204 (No Content) indicates success. Status code 404 (Not Found) is
returned when the requested container does not exist.
Note
For information about adding metadata for the following purposes, see
Chapter 7, “Additional Container Services Information” [68]:
• Container quotas
• Access log delivery
Error response codes: itemNotFound (404)
5.2.4.1. Request
This table shows the Header parameters for the Create or Update Container Metadata
Request:
X-Container-Meta-name String The container metadata. Replace the name at the end of the header
with the name of your metadata.
(Required)
This table shows the URI parameters for the Create or Update Container Metadata
Request:
Example 5.23. Create or Update Container Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
45
Developer Guide
1.1
X-Container-Meta-Book: MobyDick
X-Container-Meta-Subject: Whaling
5.2.4.2. Response
Example 5.24. Create or Update Container Metadata Response
Date: Thu, 07 Mar 2012 20:42:51 GMT
Content-Length: 0
46
Developer Guide
5.2.5. Get Container Metadata

the container.
Use a HEAD operation against the container to return the following metadata:
• How many objects are in the container (X-Container-Object-Count)

• The total bytes for all objects stored in the container (X-Container-Bytes-Used)
• Any custom metadata that is set on the container (X-Container-Meta-name)
To set and edit your custom metadata, see Section 5.2.4, “Create or Update Container
Metadata” [45].
If the container exists, a status code of 2xx (between 200 and 299, inclusive) is returned. If
the container does not exist, a status code of 404 (Not Found) is returned.
5.2.5.1. Request
This table shows the URI parameters for the Get Container Metadata Request:

Example 5.25. Get Container Metadata Request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MobyDick HTTP/1.1
5.2.5.2. Response
This table shows the Header parameters for the Get Container Metadata Response:

X-Container-Object-Count Int The number of objects in the container.
(Required)
X-Container-Bytes-Used Int The total number of bytes used for all objects in the container.
(Required)
X-Container-Meta-name String Any metadata set on the container. The name at the end of the
header is the name of your metadata.
(Required)
47
Developer Guide

X-Timestamp String An internal variable that indicates the last time an entity (account,
container, or object) was modified. The format is the same as a Unix
(Required) timestamp. The storage system uses this header to determine the
latest version. For example, during replication, the storage system
makes sure all three object replicas are up to date, and it uses the
X-Timestamp header to determine which replica is the latest. You
may notice that objects have both a Last-Modified and X-Timestamp
header. The difference between these two headers is the resolution.
Last-Modified has resolution up to one second, while X-Timestamp has
resolution up to five decimal places of one second.
Example 5.26. Get Container Metadata Response

Date: Thu, 08 Nov 2012 19:08:25 GMT
X-Container-Object-Count: 5
X-Container-Bytes-Used: 3846773
X-Container-Meta-Book: MobyDick
X-Container-Meta-Subject: Whaling
48
Developer Guide
5.2.6. Delete Container Metadata

To delete a metadata header, use POST to send an empty value for that particular header,
such as X-Container-Meta-Subject:.
If the tool you are using to communicate with Cloud Files does not support sending empty
headers (such as older versions of cURL), send the header X-Remove-Container-Meta-
name: arbitrary value, where name is the name of your custom header. arbitrary
value can be any value, and it will not be used.
To set and edit your custom metadata, see Section 5.2.4, “Create or Update Container
Metadata” [45].
A status code of 2xx (between 200 and 299, inclusive) indicates success. If the container
does not exist, a status code of 404 (Not Found) is returned.
5.2.6.1. Request
This table shows the Header parameters for the Delete Container Metadata Request:

X-Remove-Container-Meta- String The metadata to be deleted. Replace the name at the end of the
name header with the name for your metadata.
(Required)
This table shows the URI parameters for the Delete Container Metadata Request:

Example 5.27. Delete Container Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.
1
X-Remove-Container-Meta-Subject: x
5.2.6.2. Response
Example 5.28. Delete Container Metadata Response
49
Developer Guide
Date: Thu, 09 Jan 2014 22:28:22 GMT

Content-Length: 0
X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1
5.3. Object Services
You can perform the operations in the following table on objects in your Cloud Files
containers.
• object, such as MyObject
For your own requests, you must use your own account information, authentication token,
container name, and object name. You can check how to generate an authentication token
in Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token
and your account information are in the service catalog that is produced.

specified object.
system.
50
Developer Guide
5.3.1. Get Object Data

Perform GET operations against an object to retrieve the object's data
You can perform conditional GET requests by using the following HTTP headers in the
request:
• If-Match
• If-None-Match
• If-Modified-Since
• If-Unmodified-Since
These headers are documented in http://www.ietf.org/rfc/rfc2616.txt.
You can fetch a portion of the data by using the HTTP Range header. To specify multiple
ranges, separate the range specifications with a comma.
The types of range specifications are:
• Byte range specification: Use FIRST_BYTE_OFFSET to specify the start of the

data range, and LAST_BYTE_OFFSET to specify the end. You can omit the
LAST_BYTE_OFFSET and if you do, the value defaults to the offset of the last byte of
data.
• Suffix byte range specification: Use LENGTH bytes to specify the length of the data
range.
The following table shows forms of the header and the ranges of data specified.
Table 5.1. Cloud Files Supported Range Formats

Header Range of Object Data
Range: bytes=-5 The last five bytes.
Range: bytes=10-15 The six bytes of data after a 10-byte offset.
Range: bytes=10-15,-5 A multi-part response that contains the last five bytes and
the six bytes of data after a 10-byte offset. The Content-
Type of the response is then multipart/byteranges.
Range: bytes=4-6 Bytes 4 to 6 inclusive.
Range: bytes=2-2 Byte 2, the third byte of the data.
Range: bytes=6- Byte 6 and after.
Range: bytes=1-3,2-5 A multi-part response that contains bytes 1 to 3 inclusive,
and bytes 2 to 5 inclusive. The Content-Type of the
response is then multipart/byteranges.
Object data is returned in the response body. Object metadata is returned as HTTP headers.
A status code of 2xx (between 200 and 299, inclusive) indicates success. Status code 404
(Not Found) is returned if the object does not exist.
51
Developer Guide
Note
In the examples that follow that use ranges, the object contains the 10 bytes of
data 0123456789.
5.3.1.1. Request
This table shows the URI parameters for the Get Object Data Request:
{object} String The unique identifier of the object.
Example 5.29. Get Object Data Request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject
HTTP/1.1
Example 5.30. Get Object Data Request Using Range

HTTP/1.1
Range: bytes=4-6
Example 5.31. Get Object Data Request Using Multiple Ranges

HTTP/1.1
Range: bytes=1-3,2-5
5.3.1.2. Response
Example 5.32. Get Object Data Response
HTTP/1.1 200 OK
Date: Wed, 14 Jul 2010 19:37:41 GMT
Last-Modified: Mon, 12 Jun 2010 13:40:18 GMT
ETag: b0dffe8254d152d8fd28f3c5e0404a10
Content-Type: text/html
Content-Length: 512000
[ ...object content... ]
Example 5.33. Get Object Data Response Using Range

HTTP/1.1 206 Partial Content
52
Developer Guide
Date: Wed, 14 Jul 2010 19:37:41 GMT

Content-Type: application/octet-stream
Content-Range: bytes 4-6/10
Content-Length: 3
456
Example 5.34. Get Object Data Response Using Multiple Ranges

HTTP/1.1 206 Partial Content
Date: Wed, 14 Jul 2010 19:37:41 GMT
Content-Type: multipart/byteranges;boundary=4789b20f24cc4d2a8da2e552e151e6fe
Content-Length: 265
--4789b20f24cc4d2a8da2e552e151e6fe
123
--4789b20f24cc4d2a8da2e552e151e6fe
2345
--4789b20f24cc4d2a8da2e552e151e6fe--
53
Developer Guide
5.3.2. Create or Update Object

specified object.
Perform PUT operations to write, or overwrite, an object's content and metadata.
You can ensure end-to-end data integrity by including an MD5 checksum of your object's
data in the ETag header. You are not required to include the ETag header, but we
recommend its use to ensure that the storage system successfully stores your object's
content.
You can cause an object to expire after a certain date and time by using the X-Delete-
At or X-Delete-After headers during an object PUT operation. The X-Delete-
At header requires a Unix Epoch timestamp, in integer form. For example, 1348691905
represents Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific Epoch
time, you indicate when you want the object to expire, not be served, and be deleted
completely from the storage system. When Cloud Files detects one of these headers, the
system automatically stops serving that object at the specified date and time, and shortly
after the expiration date, it removes the object from the storage system.
The HTTP response includes the MD5 checksum of the data written to the storage system.
If you do not send the ETag in the request, you should compare the value returned with
your content's MD5 locally to perform the end-to-end data validation on the client side. For
manifest objects, the ETag is the MD5 checksum of the concatenated string of ETags for
each segment in the manifest, which offers change detection but not direct comparison.
For more information, refer to Section 8.2, “Create Large Objects” [70].
Note
The best checks for a successful upload are to check the ETag match with a
checksum and to see if you get a 404 (Not Found) status code when you do a
GET, HEAD, POST, or DELETE.
Objects can be assigned custom metadata by including additional HTTP headers in the PUT
request. To assign custom metadata, use an HTTP header with the X-Object-Meta-
prefix.
You can also specify Content-Type for your object. For example, you can specify
Content-Type: audio/mpeg3 for mp3 files.
A status code of 201 (Created) indicates a successful write. Any status code in the 400
range denotes failure. The 401 (Unauthorized) status code is returned upon authentication
failure. The 411 (Length Required) status code denotes a missing Content-Length or
Content-Type header in the request. If the MD5 checksum of the data written to the
storage system does NOT match the optionally supplied ETag value, a 422 (Unprocessable
Entity) status code is returned.
No response body is returned.
54
Developer Guide
Error response codes: unauthorized (401), lengthRequired (411), unprocessableEntity

(422)
5.3.2.1. Request
This table shows the Header parameters for the Create or Update Object Request:

ETag String The MD5 checksum of your object's data.
(Optional)
Content-Type String The media type of the entity-body sent. If not specified, the
Content-Type is guessed, by using the Python mimetypes library,
(Optional) based on the object path.
Content-Disposition String The new browser behavior for the file, so that the downloader can
save the file rather than displaying it using default browser settings.
(Optional)
Content-Encoding String The underlying media type of the compressed file.
(Optional)
X-Delete-At Int The certain date, in the format of a Unix Epoch timestamp, when the
object will be removed.
(Optional)
X-Delete-After Int The certain date, in the format of a Unix Epoch timestamp, after which
the object will be removed.
(Optional)
X-Object-Meta-name String The custom object metadata. name at the end of this header
represents the name of your metadata.
(Optional)
X-Detect-Content-Type String If you set this header to True, the Content-Type that is sent in the
request (if any) is ignored, and Content-Type is guessed by using
(Optional) the Python mimetypes library based on the object path.
This table shows the URI parameters for the Create or Update Object Request:

Example 5.35. Create or Update Object Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject
HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
X-Delete-At: 1339429105
Content-Disposition: attachment; filename=platmap.mp4
Content-Type: video/mp4
Content-Encoding: gzip
X-Object-Meta-PIN: 1234
[ ...object content... ]
55
Developer Guide
5.3.2.2. Response
Example 5.36. Create or Update Object Response
Date: Thu, 07 Jun 2010 18:57:07 GMT
ETag: d9f5eb4bba4e2f2f046e54611bc8196b
Content-Length: 0
56
Developer Guide
5.3.3. Delete Object

DELETE operations on an object permanently remove an object from the storage system
(data and metadata).
Deleting an object is processed immediately at the time of the request. Any subsequent
GET, HEAD, POST, or DELETE operations return a 404 (Not Found) error unless object
versioning is on and other versions exist. For more information about object versioning, see
Section 8.6, “Object Versioning” [79].
Objects with the X-Delete-At or X-Delete-After header assigned are deleted

within one day of the expiration time, and the object is not served immediately after
the expiration time. For more details, refer to Section 8.5, “Expiring Objects with the X-
Delete-After and X-Delete-At Headers” [78].
returned when the object does not exist.
For information about bulk deletions, see Section 12.3, “Bulk Delete” [104].
5.3.3.1. Request
This table shows the URI parameters for the Delete Object Request:

Example 5.37. Delete Object Request

DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
5.3.3.2. Response
Example 5.38. Delete Object Response
57
Developer Guide
Date: Thu, 10 Jun 2010 20:59:39 GMT

58
Developer Guide
5.3.4. Copy Object

system.

PUT v1/{account}/{container}/{object} Using the X-Copy-From header, copies an existing object to
system bu us.
Suppose you upload a file with the wrong object name or content type, or you need to
move some objects to another container. Without a server-side object copy feature, you
would need to repeat uploading the same content and then delete the existing object.
With a server-side object copy feature, you can save the step of re-uploading the content
and thus also save the associated bandwidth charges, if any were to apply.
There are two ways to copy an existing object to another object in Cloud Files.
One way is to use a PUT request to the new object (the destination) location, but add the
X-Copy-From header to designate the source of the data. The header value should be the
container and object name of the source object in the form of /container/object. The
HTTP specification of a PUT request with the X-Copy-From header requires a Content-
Length header, but the storage system does not use the Content-Length to perform
the operation. For this reason, you can simply send a Content-Length of zero (0).
Note
You cannot copy an object larger than 5 GB (by default). For more information
about how to handle objects larger than 5 GB, see Section 8.2, “Create Large
Objects” [70].
Example 5.39. Copy Object Method 1 - Using PUT
PUT /v1/account/destinationContainer/destinationObject HTTP/1.1

Host: storageURL
X-Auth-Token: yourAuthToken
X-Copy-From: /sourceContainer/sourceObject
Content-Length: 0
The second way to perform an object copy is similar. Use a COPY request to the existing
object, and include the Destination header to specify the destination of the copy. The
header value is the container and new object name in the form of /container/object.
Unlike the first method, this method does not require a Content-Length header.
Example 5.40. Copy Object Method 2 - Using COPY
COPY /v1/account/sourceContainer/sourceObject HTTP/1.1

Host: storageURL
X-Auth-Token: yourAuthToken
Destination: /destinationContainer/destinationObject
59
Developer Guide
With both of these methods, the destination container must exist before attempting the
copy.
The status code for a successful object copy is 201 (Created).
Note
If you are copying many objects, you can improve the total copy time by
issuing several concurrent COPY commands. Because Cloud Files is a distributed
storage system, your concurrent COPY commands run on separate machines
simultaneously, which is much better than waiting for one copy to finish before
starting the next COPY command. As a rule of thumb, you can run up to 100
concurrent COPY commands per container (running more will have diminishing
improvement).
Another option is bulk importing of data. For information about bulk imports,
see Section 12.1, “Bulk Importing of Data” [102].
If you want to move the object rather than copy it, send a DELETE request to the source
object after copying it. A move is simply a COPY followed by a DELETE. All metadata is
preserved during the object copy. Note that you can set metadata on the request to copy
the object (with either the PUT or the COPY) and the metadata overwrites any conflicting
keys on the destination object.
Your account is not charged when you copy or move your objects within the same data
center using the internal network URI, ServiceNet, as the storage URL. You can find your
ServiceNet endpoint in the service catalog created when you authenticate your session. For
information on how to authenticate your session, see Section 3.1, “Authentication” [10].
As shown in the partial service catalog example below, the ServiceNet URI is listed as
internalURL. The name is your Cloud Files storage URL with snet- pre-pended to it. If
you do not know which data center you are working in, you can find it in the Cloud Control
Panel. (For more information about service access endpoints, see Section 3.3, “Service
Access Endpoints” [20].)
Example 5.41. Data Center Endpoints
"endpoints": [
{
"region": "DFW",
"internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
"tenantId": "MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
"publicURL": "https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c"
},
{
"region": "ORD",
"internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/
MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
"tenantId": "MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
"publicURL": "https://storage101.ord1.clouddrive.com/v1/
MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c"
60
Developer Guide
}
]
5.3.4.1. Request
This table shows the Header parameters for the Copy Object Request:

X-Copy_From String Used with PUT, the container and object name of the source object in
the form of /container/object.
(Optional)
Content-Length Int Used with PUT, the content length. Zero (0) is always acceptable here
for this operation.
(Required)
Destination String Used with COPY, the container and object name of the destination
object in the form of /container/object.
(Optional)
This table shows the URI parameters for the Copy Object Request:

Example 5.42. Copy Object Request Using PUT

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/
MyDestinationContainer/MyDestinationObject HTTP/1.1
X-Copy-From: /MySourceContainer/MySourceObject
Content-Length: 0
Example 5.43. Copy Object Request Using COPY

COPY /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MySourceContainer/
MySourceObject HTTP/1.1
Destination: /MyDestinationContainer/MyDestinationObject
5.3.4.2. Response
This operation does not return a response body.
61
Developer Guide
5.3.5. Get Object Metadata

HEAD operations on an object are used to retrieve object metadata and other standard
HTTP headers.
The only required header to be sent in the request is X-Auth-Token for the authorization
token.
A status code of 200 (OK) indicates success. Status code 404 (Not Found) is returned when
the object does not exist.
This operation does not return a response body. Metadata is returned as HTTP headers.
Note
The HEAD return code for an object is different than that of a container.
The HEAD request does not return a message body in the response, so a 2xx
status code denotes success. When a HEAD request is performed against
the container, it queries the container databases, and it does not retrieve
the content from them. Thus, this returns the 204 (No Content) status code.
However, when a HEAD request is performed against the object, it returns a
200 OK status code because it can view the content.
5.3.5.1. Request
This table shows the URI parameters for the Get Object Metadata Request:
Example 5.44. Get Object Metadata Request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
5.3.5.2. Response
This table shows the Header parameters for the Get Object Metadata Response:
X-Timestamp String An internal variable that indicates the last time an entity (account,
container, or object) was modified. The format is the same as a Unix
62
Developer Guide

(Required) timestamp. The storage system uses this header to determine the
latest version. For example, during replication, the storage system
makes sure all three object replicas are up to date, and it uses the
X-Timestamp header to determine which replica is the latest. You
may notice that objects have both a Last-Modified and X-Timestamp
header. The difference between these two headers is the resolution.
Last-Modified has resolution up to one second, while X-Timestamp has
resolution up to five decimal places of one second.
Last-Modified String An internal variable that indicates the last time an entity (account,
container, or object) was modified. For Last-Modified, the time zone
(Required) is UTC. You may notice that objects have both a Last-Modified and X-
Timestamp header. The difference between these two headers is the
resolution. Last-Modified has resolution up to one second, while X-
Timestamp has resolution up to five decimal places of one second.
Example 5.45. Get Object Metadata Response

HTTP/1.1 200 OK
Date: Thu, 10 Jun 2010 20:59:39 GMT
Last-Modified: Fri, 11 Jun 2010 13:40:18 GMT
ETag: 8a964ee2a5e88be344f36c22562a6486
X-Object-Meta-Meat: Bacon
X-Object-Meta-Fruit: Apple
X-Object-Meta-Veggie: Beans
X-Object-Meta-Dairy: Cheese
63
Developer Guide
5.3.6. Update Object Metadata

You can set or update your custom metadata for existing objects by using a POST request
to the object name.
Metadata is set by using the header X-Object-Meta-name: Foo where name is

the custom name for your metadata and Foo is the value. You can also set values for X-
Delete-At and X-Delete-After to set expirations for objects.
To remove previously-set object metadata, perform a POST request to the object name
with X-Remove-Object-Meta-name: Foo where name is the name of your metadata.
Foo is any term, and it will not be used. You must, however, send some value with the
request. Otherwise, the metadata is not removed.
For information on working with metadata when copying objects, see Section 5.3.4, “Copy
Object” [59].
Deleting Object Metadata

All the object metadata is set at the same time. If you want to edit or remove
one header, simply POST all other headers leaving out the header that you
want to remove. This means that if you delete one entry without posting the
others, the others will also be deleted at that time.
To remove all metadata on an object, simply perform a POST request for the
object with no metadata specified. However, to remove container metadata,
you must send the header with an empty value.
A status code of 202 (Accepted) indicates success. Status code 404 (Not Found) is returned
if the requested object does not exist.
This operation does not return a response body.
5.3.6.1. Request
This table shows the Header parameters for the Update Object Metadata Request:

X-Object-Meta-name String The container metadata. name represents the name of your
metadata.
(Optional)
64
Developer Guide

X-Delete-At Int The date, in the format of a Unix Epoch timestamp, when the object
will be removed.
(Optional)
X-Delete-After Int The date, in the format of a Unix Epoch timestamp, after which the
object is removed.
(Optional)
This table shows the URI parameters for the Update Object Metadata Request:

Example 5.46. Update Object Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
X-Object-Meta-Fruit: Apple
X-Object-Meta-Veggie: Carrot
5.3.6.2. Response
Example 5.47. Update Object Metadata Response
HTTP/1.1 202 Accepted
Date: Thu, 07 Jun 2007 20:59:39 GMT
Content-Length: 0
65
Developer Guide
6. Pseudo Hierarchical Folders and

Directories
Although you cannot nest directories in Cloud Files, you can simulate a hierarchical
structure within a single container by adding forward slash characters (/) in the object
name. To navigate the pseudo directory structure, you can use the delimiter query
parameter. For an illustration, see the examples below.
Note
In the example below, the objects reside in a container called backups. Within
that container, the objects are organized in a pseudo directory called photos.
Keep in mind that the container name is not displayed in the example, but
that it is a part of the object URIs. For instance, the URI of the picture me.jpg
is https://storage.clouddrive.com/v1/CF_xer7_343/backups/
photos/me.jpg.
To display a list of all the objects in the storage container, use GET without a delimiter
or prefix.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups
The system returns status code 200 OK and the requested list of the objects.
photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg
Use the delimiter parameter to limit the displayed results. Any character may be used as a
delimiter. However, to use delimiter with pseudo directories, use the slash (/).
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?delimiter=/
The system returns status code 200 (OK) and the requested matching objects. Because
the request used the slash, only the pseudo directory photos/ displays. Keep in mind
that the returned values from a slash delimiter query are not real objects. They have a
Content-Type of application/directory and are in a subdir section of JSON and
XML results.
photos/
Use the prefix parameter with the delimiter parameter to view the objects inside a
pseudo directory, including further nested pseudo directories.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?prefix=
photos/&delimiter=/
The system returns status code 200 (OK) and the objects and pseudo directories within the
top level pseudo directory.
66
Developer Guide
photos/animals/
photos/plants/
photos/me.jpg
There is no limit to the amount of nested pseudo directories you can create. In order to
navigate through them, use a longer prefix parameter coupled with the delimiter
parameter. In the sample output below, there is a pseudo directory called dogs within the
pseudo directory animals. In order to navigate directly to the files contained within dogs,
enter the below command.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?prefix=
photos/animals/dogs/&delimiter=/
The system returns status code 200 (OK) and the objects and pseudo directories within the
nested pseudo directory.
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
67
Developer Guide
7. Additional Container Services

Information
The following section describes additional metadata options for containers in Cloud Files.
7.1. Container Quotas
The container_quotas middleware implements simple quotas that can be imposed on Cloud
Files containers by a user (most likely the account administrator) with the access to set
container metadata. Setting container quotas can be useful for limiting containers for non-
admin users, formpost uploads, or just as a self-imposed sanity check.
Any object PUT operations that exceed the quotas return a 413 response (request entity
too large) with a descriptive body.
Because the storage system is a true distributed system and because it accepts simultaneous
requests, the quotas may not be enforced exactly. For example, if the quota is 5 GB and
two users try to store a 5 GB file at the exact same time, both would be allowed to store
the file since at the time of both requests the container had sufficient remaining quota.
Also, for chunked file uploads, the storage system cannot reject transfers that will
eventually exceed the quota because the storage system does not know whether the end
of the file will exceed the quota.
Quotas are set by adding metadata to the container. The available metadata values are
described in the following table.
Table 7.1. Metadata Values for Setting Container Quotas

Header for Metadata Use
X-Container-Meta-Quota-Bytes Maximum size of the container, in bytes
X-Container-Meta-Quota-Count Maximum object count of the container
7.2. Access Log Delivery

You can use Access Log Delivery to analyze the number of requests for each object, the
client IP address, and time-based usage patterns (such as monthly or seasonal usage).
Access Log Delivery is set on the container, and every object in the container is tracked. To
enable access logs for a container, set the metadata flag X-Container-Meta-Access-
Log-Delivery flag to True. If you have multiple containers that you want to track, you
must set the metadata header to TRUE for each container. When your first log is delivered,
the container .ACCESS_LOGS is created. This container holds the access logs for every
container for which you turn on logging. Log files exist until you delete them. To turn off
logging, set X-Container-Meta-Access-Log-Delivery flag to FALSE.
Log files are named according to this pattern: container

name, log date, log hour, and MD5_hash such as
Media/2012/10/01/16/096e6c4473f235db081deb51f42a8d98.log.gz . In this
68
Developer Guide
example, Media is the name of the container, October 1, 2012 is the date, and 16 is the
hour the logs are from. There may be multiple files for a given hour because the storage
system splits log files based on both time and log file size. All times in the access logs are
UTC time.
Within the gzipped logs, the format of the entries is similar to National Center for
Supercomputing Applications (NCSA) combined log format, but without cookies. The
pattern is below. The dashes ("-") note fields which the NCSA combined log format
dictates be present but which Cloud Files does not capture. The format is:
client_ip - - [day/month/year:hour:minute:second timezone

“method request HTTP_version” return_code bytes_sent “referrer”
“user_agent”
The following example shows the log entries.
Example 7.1. Example Access Log Entries
50.56.228.64 - - [27/08/2012:16:50:22 +0000] "PUT /v1/

MossoCloudFS_bb88c7b9-ea5b-49af-82fc-376ff241963c/CharacterTest_%2521
HTTP/1.0" 401 0 "-" "python-requests/0.13.8
CPython/2.7.3 Linux/3.2.0-29-generic"
50.56.228.64 - - [27/08/2012:16:53:49 +0000] "PUT /v1/
/object_%2521 HTTP/1.0" 201 118 "-" "python-requests/0.13.8
50.56.228.64 - - [27/08/2012:16:53:47 +0000] "PUT /v1/
50.56.228.64 - - [27/08/2012:16:50:36 +0000] "PUT /v1/
69
Developer Guide
8. Additional Object Services Information

The following sections provide additional information about using objects in Cloud Files.
8.1. Chunked Transfer Encoding

You can upload data without needing to know in advance the amount of data to be
uploaded. You can do this by specifying an HTTP header of Transfer-Encoding:
chunked and not using a Content-Length header. A good use of this feature would be
performing a DB dump, piping the output to gzip, and then piping the gzip file directly to
Cloud Files without having to write the data to disk to compute the file size. If you attempt
to upload more than 5 GB, the server will close the connection and remove the previously
sent data from the system. You must ensure that the data that you transfer will be less
than 5 GB or split it into 5 GB chunks, each in its own storage object.
If you have files that are larger than 5 GB and want to use Cloud Files, you can segment
them prior to upload, upload them to the same container, and then use a manifest file to
allow downloading of a concatenated object containing all the segmented objects. For
more information, see Section 8.2.1, “Dynamic Large Object Creation” [72].
Example 8.1. Upload Unspecified Quantity of Content Request

HTTP/1.1
Transfer-Encoding: chunked
X-Object-Meta-PIN: 1234
Example 8.2. Upload Unspecified Quantity of Content Response

19
A bunch of data broken up
D
into chunks.
0
8.2. Create Large Objects

The content of an object cannot be larger than 5 GB (by default). However, you can store
larger content by using two types of objects:
• Segment objects: You divide your content into pieces and upload each piece into its own
object, which is a segment object.
• Manifest objects: You create a manifest object that "points to" the segment objects.
Segment objects do not have any special features and can be created, updated,
downloaded, and deleted. However, a manifest object is special – when you download, the
system concatenates the contents of the segment objects and returns this in the response
body of the request. This behavior extends to the response headers returned by GET and
HEAD operations. The Content-Length is the total size of all segment objects and
70
Developer Guide
the ETag is calculated by taking the ETag value of each segment, concatenating them
together, and then returning the MD5 checksum of the result.
Note
If you use the COPY operation using a manifest object as the source, the new
object is a "normal" object (not segmented). If the total size of the source
segment objects exceeds 5GB, the COPY operation will fail. However, you can
make a duplicate of the manifest object. This new object can be larger than
5GB.
There are two types of manifest objects as follows:
• Dynamic Large Objects: The manifest object has no content. However, it has X-Object-
Manifest metadata. The value of this is container/prefix , where container is
the name of the container where the segment objects are stored and prefix is a string
that all the segment objects have in common.
• Static Large Objects: The manifest object content is an ordered list of the names of the
segment objects in JSON format.
While both types of manifest objects have similar behavior, there are differences as
explained in the following table.
71
Developer Guide
Table 8.1. Comparison of Static and Dynamic Large Objects

Feature Static Large Object Dynamic Large Object
End-to-end integrity Assured. The list of segments includes Not guaranteed. The eventual
the MD5 checksum (ETag) of each consistency model means that
segment. You cannot upload the although you may have uploaded a
manifest object if the ETag in the segment object, it may not appear
list differs from the segment object in the container listing until later. If
already uploaded. If a segment you download the manifest before it
is somehow lost, an attempt to appears in the container, it will not
download the manifest object will form part of the content returned in
result in an error. response to a GET request.
Upload order The segment objects must be uploaded You can upload manifest and
before the manifest object. segment objects in any order. We
recommend that you upload the
manifest object after the segments
in case a premature download of the
manifest occurs. However, this is not
enforced.
Removal or addition of segment You cannot add or remove segment You can upload new segment objects
objects objects from the manifest. However, or remove existing segments –
you can create a completely new the names must simply match the
manifest object of the same name with <prefix> supplied in X-Object-
a different manifest list. Manifest.
Segment object size and number Segment objects must be at least 1MB Segment objects can be of any size.
in size (by default). The final segment
object can be any size. At most 1000
segments are supported (by default)
Segment object container name The manifest list includes the container All segment objects must be in the
name of each object, i.e., segment same container.
objects may be in different containers.
Manifest object metadata The object has X-Static-Large- The X-Object-Manifest value is
Object set to True. You do not set the container/prefix indicating
this metadata directly. Instead the where the segment objects are
system sets it when you PUT a static located. You supply this request
manifest object. header in the PUT operation
Making a copy of the manifest object To make a copy of the manifest The COPY operation does not create
object, include the ?multipart- a manifest object. To duplicate
manifest=get query string with a manifest object, use the GET
the COPY operation. The new object operation to read the value of X-
contains the same manifest as the Object-Manifest and use this
original. The segment objects are not value in the X-Object-Manifest
copied. Instead, both the original and request header in a PUT operation.
new manifest objects share the same This creates a new manifest object
set of segment objects. that shares the same set of segment
objects as the original manifest
object.
8.2.1. Dynamic Large Object Creation

Objects that are larger than 5 GB must be segmented, prior to upload. You then upload
the segments as you would any other object. You create a manifest object telling Cloud
Files how to find the segments of the large object. The segments remain individually
addressable, but retrieving the manifest object streams all the segments concatenated.
There is no limit to the number of segments that can be a part of a single large object.
Dynamic Large Objects rely on the eventual consistency model.
72
Developer Guide
Note
The eventual consistency model means that although you may have uploaded
a segment object, it may not appear in the container listing until later. If you
download the manifest before it appears in the container, it will not form part
of the content returned in response to a GET request.
To ensure that the download works correctly, you must upload all the object segments
to the same container and that ensure each object name is prefixed in such a way that
their names sort in the order in which they should be concatenated. You also create and
upload a manifest file. The manifest file is simply a zero-byte file with the extra X-Object-
Manifest: container/prefix header, where container is the container that
the object segments are in and prefix is the common prefix for all the segments. The
container and common prefix must be UTF-8 encoded and URL-encoded in the X-Object-
Manifest header.
It is best to upload all the segments first and then create or update the manifest. With this
method, the full object will not be available for downloading until the upload is complete.
Also, you can upload a new set of segments to a second location and then update the
manifest to point to this new location. During the upload of the new segments, the original
manifest will still be available to download the first set of segments.
Note
The segments are deletable by the user at any time. If a segment is deleted by
mistake, a Dynamic Large Object, having no way of knowing the segment was
ever there, ignores the deleted file, and the user is returned an incomplete file.
Example 8.3. Upload Segment of a Large Object Request

HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
Example 8.4. Upload Segment of a Large Object Response

s
No response body is returned. A status code of 201 (Created) indicates a successful write.
Status code 411 (Length Required) indicates that the Content-Length header is missing.
If the MD5 checksum calculated by the storage system does NOT match the optionally
supplied ETag value, a 422 (Unprocessable Entity) status code is returned.
You can continue uploading segments as this example shows, prior to uploading the
manifest.
73
Developer Guide
Example 8.5. Upload Next Segment of the Large Object Request

HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
Example 8.6. Upload Next Segment of the Large Object Response

w
Next, upload the manifest that you created that indicates the container in which the object
segments reside. Note that uploading additional segments after the manifest is created will
cause the concatenated object to be that much larger but you do not need to recreate the
manifest file for subsequent additional segments.
Example 8.7. Upload Manifest Request

HTTP/1.1
Content-Length: 0
X-Object-Manifest: container/prefix/object/segments
Example 8.8. Upload Manifest Response

[...]
A GET request to the manifest object returns the concatenation of the objects from the
manifest.
Note
The ETag in the response for a GET or HEAD on the manifest file is the MD5
sum of the concatenated string of ETags for each of the segments in the
manifest. Usually, the ETag is the MD5 sum of the contents of the object, and
that holds true for each segment independently. But it is not meaningful to
generate such an ETag for the manifest itself, so this method was chosen to at
least offer change detection.
The response's Content-Type for a GET or HEAD request on the manifest will be the
same as the Content-Type set during the PUT request that created the manifest. You can
easily change the Content-Type by reissuing the PUT request.
8.2.2. Static Large Object Creation

Static Large Object (SLO) support is similar to Dynamic Large Object (DLO) support because
it allows you to upload many objects concurrently and afterwards downloads them as a
single object. However, unlike Dynamic Large Object support, Static Large Object support
does not rely on eventual consistency model for the container listings. Instead, Static Large
Object support uses a user-defined manifest of the object segments.
74
Developer Guide
The benefits of using Static Large Objects are:
• Uploads and downloads of Static Large Objects can be in different containers, which can
improve performance.
• There is an explicit list of segments, instead of an implied list as with DLOs.
A Static Large Object is created in two steps:
1. Divide your content into pieces and create (upload) a segment object to contain each
piece. You must record the ETag response header returned by the PUT operation.
Alternatively, you can calculate the MD5 checksum of the segment prior to uploading
and include this in the ETag request header – this ensures that the upload cannot
corrupt your data.
The maximum number of object segments per Static Large Object is 1,000. Each
segment, except for the final one, must be at least one megabyte.
2. List the name of each segment object along with its size and MD5 checksum in order.
Create a manifest object. You indicate that this is a manifest object by including
the ?multipart-manifest=put query string at the end of the manifest object name.
8.2.2.1. Uploading the Segments

The first thing to do is to upload your segment objects. All the segments, except the last
one, need to be larger than 1 megabyte (1048576 bytes). It may help organizationally
to keep them in the same container, but it is not required. You will need the following
information about each segment for the next step, uploading the manifest object:
• path – the container and object name in the following format:

containerName/objectName
• etag – the ETag header from the successful 201 response of the PUT when you
uploaded the segment. This is the MD5 checksum of the segment object's data.
• size_bytes – the segment object's size in bytes. This should match the Content-
Length of that object.
8.2.2.2. Uploading the Manifest

After you have uploaded the objects to be concatenated, you upload a manifest object.
The request must be a PUT with the following query parameter at the end of the manifest
object name:
?multipart-manifest=put
The body of the PUT operation is an ordered list of files in JSON data format. The data to
be supplied for each segment is:
• path – the container and object name in the following format:

containerName/objectName
• etag – the ETag header from the successful 201 response of the PUT when you
uploaded the segment. This is the MD5 checksum of the segment object's data.
75
Developer Guide
• size_bytes – the segment object's size in bytes. This should match the Content-
Length of that object.
Following is an example containing three segment objects. This example illustrates that
in contrast to dynamic large objects, you can use a number of containers and the object
names do not have to conform to a specific pattern.
Example 8.9. Static Large Object Manifest List

json:[
{
"path": "/mycontainer/objseg1",
"etag": "0228c7926b8b642dfb29554cd1f00963",
"size_bytes": 1468006
},
{
"path": "/mycontainer/pseudodir/seg-obj2",
"etag": "5bfc9ea51a00b790717eeb934fb77b9b",
"size_bytes": 1572864
},
{
"path": "/other-container/seg-final",
"etag": "b9c3da507d2557c1ddc51f27c54bae51",
"size_bytes": 256
}
]
The Content-Length request header must contain the length of the JSON content
– not the length of the segment objects. However, after the PUT operation completes,
the Content-Length metadata is set to the total length of all the object segments. A
similar situation applies to the ETag . If used in the PUT operation, it must contain the
MD5 checksum of the JSON content. The ETag metadata value is then set to be the MD5
checksum of the concatenated ETag values of the object segments. You can also set the
Content-Type request header and custom object metadata.
When the PUT operation sees the ?multipart-manifest=put query string, it reads
the request body and verifies that each segment object exists and that the sizes and ETags
match. If there is a mismatch, the PUT operation will fail.
On upload, the middleware will head every segment passed in and verify the size and
ETag of each. If any of the objects do not match (not found, size/ETag mismatch, below
minimum size), Cloud Files issues a 4xx status code. If everything does match, Cloud Files
issues a 2xx status code.
If everything matches, the manifest object is created. The X-Static-Large-Object

metadata is set to True indicating that this is a static object manifest.
When the manifest object is uploaded, you are more or less guaranteed that every segment
in the manifest exists and that it matches the specifications. However, nothing prevents a
user from breaking the Static Large Object download by deleting or replacing a segment
referenced in the manifest. Users should use caution when handling the segments.
The order of the segments listed in the manifest determine the order in which the
segments will be concatenated on download. The manifest can reference objects in
separate containers, which improves concurrent upload speed. Objects can be referenced
by multiple manifests.
76
Developer Guide
8.2.2.3. Retrieving a Large Object

A GET request to the manifest object returns the concatenated content of the segment
objects listed in the manifest. If any of the segments from the manifest are not found or
their ETag or Content-Length no longer match, the GET operation will fail and you will
receive partial results (up to the point of the failure due to not matching). As a result, a 409
(Conflict) status code is logged.
The headers from the GET or HEAD request return metadata for the manifest object as
shown below:
• Content-Length: The total size of the Static Large Object (the sum of the sizes of the
segments in the manifest)
• X-Static-Large-Object: True
• ETag: The ETag of the Static Large Object (generated the same way as Dynamic Large
Object)
The GET request with the following query parameter returns the actual manifest file
contents:
?multipart-manifest=get
The response body contains generated JSON. The resulting list will not be identically
formatted like the manifest you originally used in the PUT operation (?multipart-
manifest=put).
The call’s main purpose is for debugging.
8.2.2.4. Deleting a Large Object

A DELETE operation on a manifest object deletes the manifest object itself. The segment
objects are not affected.
A DELETE operation with the following query parameter deletes all segment objects
in the manifest, and then, if all are successfully deleted, the manifest object itself. A
failure response will be similar to those for the bulk delete operation (Section 12.3, “Bulk
Delete” [104]).
?multipart-manifest=delete
8.2.2.5. Modifying a Large Object

PUT and POST operations work as expected.
A PUT overwrites the manifest object (and leaves the segments alone).
APOST changes the manifest file's metadata and contents, as with any other object.
8.2.2.6. Listing of Containers with Static Large Objects

In a container listing, the size listed for a Static Large Object manifest object is the total
size of the concatenated segments in the manifest, not the size of the manifest file itself.
77
Developer Guide
The overall X-Container-Bytes-Used for the container (and for the account) does not
reflect the total size of the manifest, but the actual size of the stored JSON data. This allows
you to see the total size of the Static Large Object in a container listing, but does not inflate
the bytes used for the container or the account.
8.3. Enabling File Compression with the Content-

Encoding Header
The Content-Encoding header allows a file to be compressed while still preserving the
identity of the underlying media type of the file, for example, a video.
The object must be compressed before it is uploaded. Cloud Files does not do any
automatic compression. The Content-Encoding header enables the client to set the
metadata appropriately.
In the following example, the Content-Encoding header indicates the type of encoding
used on the data.
Example 8.10. Request with Content-Encoding

Content-Type: video/mp4
Content-Encoding: gzip
8.4. Enabling Browser Bypass with the Content-

Disposition Header
When an object is assigned the Content-Disposition header, you can override a
browser's default behavior for a file so that the browser prompts to save the file rather
than displaying it using default browser settings.
In the following example, the Content-Disposition header is assigned with an

attachment type that indicates how the file should be downloaded.
Example 8.11. Request with Content-Disposition

HTTP/1.1
Content-Type: image/tiff
Content-Disposition: attachment; filename=platmap.tif
8.5. Expiring Objects with the X-Delete-After

and X-Delete-At Headers
When an object is assigned either an X-Delete-After or X-Delete-At header when
performing a PUT or POST on the object, it is scheduled for deletion. This feature is helpful
78
Developer Guide
for objects that you do not want to permanently store, such as log files, recurring full
backups of a dataset, or documents or images that you know will be outdated at a future
time.
Objects with the X-Delete-At or X-Delete-After header assigned are deleted

within one day of the expiration time, and the object is not served immediately after the
expiration time. Refer to Expiring Objects for more details.
The X-Delete-At header requires a Unix Epoch timestamp, in integer form. For example,
1348691905 represents Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific
Epoch time, you indicate when you want the object to expire, not be served, and be
deleted completely from the storage system.
The X-Delete-After header takes an integer number of seconds that represents the
amount of time from now that you want the object to be deleted. The proxy server that
receives the request converts this header into an X-Delete-At header and calculates the
deletion time using its current time plus the value given in seconds.
For existing objects that you want to assign expiration headers to, use the POST operation.
In the following example, the X-Delete-At header is assigned with a Unix

Epoch timestamp in integer form for Mon, 11 Jun 2012 15:38:25 GMT. Use http://
www.epochconverter.com/ for example timestamps and a batch converter.
Example 8.12. X-Delete-At Request
HTTP/1.1
Content-Type: image/jpeg
X-Delete-At: 1339429105
In the following example, the X-Delete-After header is assigned a value in seconds,

equivalent to 10 days. After this time, the object expires.
Example 8.13. X-Delete-After Request
HTTP/1.1
X-Delete-After: 864000
8.6. Object Versioning
Object versioning allows you to store multiple versions of your content to recover from
unintended overwrites and deletions. It provides an easy method to implement version
control which can be used on any type of content. Rackspace strongly recommends that
you put non-current objects in a separate container from where the current versions exist.
Once you enable object versioning, new data written to an object causes the last-current
version to be written to the separate container. Each of the non-current versions has a
timestamp appended to it, so you know when it was originally created.
79
Developer Guide
To enable object versioning, create a container where your non-current versions will be
written. Next, set the metadata X-Versions-Location header on the container that
holds the current versions of your objects. Set the metadata header to point to the new
non-current version container that you created. This is where your non-current versions will
be stored. Once this is done, each object in your current-version container will have object
versioning enabled. Changes to the objects automatically create non-current versions in the
separate container.
Nothing is written to the non-current version container when you initially PUT an object
into the current-version container. Only when you make edits to the objects with a PUT
request will you create non-current versions. These non-current versions are labeled
according to the schema below.
Naming Schema: Non-current versions are assigned the name {length}{objectName}/

{timestamp}, where {length} is the 3-character zero-padded hexadecimal character
length of the {objectName} and {timestamp} from when it was originally created as a
current version.
Any return status in the 2xx range, such as 202 (Accepted), denotes success. Status codes
in the 4xx or 5xx range denote failure. You should retry your request if you receive an
error. Note, however, that if you have specified a container that does not exist as your non-
current version container, a status of 412 (Precondition Failed) returns when you edit the
versioned object. If you receive this error, check to see if the container exists.
A GET to a versioned object returns the current version of the object without having to do
any request redirects or metadata lookups.
A POST to a versioned object only updates the object's metadata. It does not create a new
version of the object. In other words, new versions are only created when the content of
the object changes.
A DELETE to a versioned object removes the current version of the object and replaces it
with the next-most current version, moving it from the non-current container to the current
container. This next-most current version carries with it any metadata last set on it. If want
to completely remove an object and you have five total versions of it, you must DELETE it
five times.
Note
A large-object manifest file cannot be versioned, but it can point to versioned
segments.
To turn off object versioning on your current version container, remove its X-Versions-
Location metadata by sending a key value that is an empty string.
Example 8.14. Object Versioning with cURL
Make sure a version-storing container exists by creating it if necessary. This example names
it versions. Then create a container with the X-Versions-Location header. In
this example, this container is named current. You can also add the X-Versions-
Location header to an existing container. In this example, the name of the container is
versions. The location for the current version is the container current.
80
Developer Guide
1. Create a container named versions.

curl -i -XPUT -H "X-Auth-Token: yourAuthToken" http://yourStorageUrl/
versions
2. Create a container named current with the X-Versions-Location header that

references versions.
curl -i -XPUT -H "X-Auth-Token: yourAuthToken" \
-H "X-Versions-Location: versions" http://yourStorageUrl/current
3. Create an object (the first version).

curl -i -XPUT --data-binary 1 -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl/current/myobject
4. Now create a new version of that object.

curl -i -XPUT --data-binary 2 -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl}/current/myobject
5. See a listing of the older versions of the object. (The example includes the hex number
for the length of the filename.)
curl -i -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl/versions?prefix=008myobject/
6. Now delete the current version of the object and see that the older version is gone.
curl -i -XDELETE -H "X-Auth-Token: yourAuthToken" \

http://yourStorageUrl>/current/myobject
curl -i -H "X-Auth-Token: yourAuthToken " \
http://yourStorageUrl/versions?prefix=008myobject/
81
Developer Guide
9. API Operations for CDN Services

This chapter provides further description for several of the API operations described in
Chapter 5, “API Operations for Storage Services” [26]. These API operations have a specific
purpose for the Content Delivery Network (CDN) service that is available in Cloud Files.
You direct the REST API methods described to the endpoints described in the
cloudFilesCDN section of the service catalog that you obtain during successful
authentication. (For more information, see Section 3.1, “Authentication” [10] and
Section 3.3, “Service Access Endpoints” [20].)
A CDN-enabled container is a public container that is served by Akamai's Content

Distribution Network. The files in a CDN-enabled container are publicly accessible and do
not require an authentication token for read access. However, uploading content into a
CDN-enabled container is a secure operation and does require a valid authentication token.
(Private containers are not CDN-enabled and the files in a private container are not publicly
accessible.)
The following sections describe the operations that you can perform within the storage
system:
• Chapter 9, “API Operations for CDN Services” [82] describes operations that you can
perform at the account level for Cloud Files CDN services.
• Section 9.2, “CDN Container Services” [84] describes operations that you can perform
on containers.
• Section 9.3, “CDN Object Services” [93] describes operations that you can perform on
objects.
9.1. CDN Account Services

You can perform the operation in the following table at the account level of your Cloud
Files CDN account.
For your own requests, you must use your own account information and authentication
token. You can check how to generate an authentication token in Section 3.1.2,
“Retrieving the Authentication Token” [10]. Your authentication token and your account
information are in the service catalog that is produced.

GET v1/{account}{?enabled_only,limit, Lists CDN-enabled containers sorted by name.
marker,end_marker,format}
82
Developer Guide
9.1.1. List CDN-Enabled Containers

GET v1/{account}{?enabled_only,limit, Lists CDN-enabled containers sorted by name.
marker,end_marker,format}
GET operations against the cloudFilesCDN endpoints for an account retrieve a list
of CDN-enabled containers. (For the CDN endpoints, see Section 3.3, “Service Access
Endpoints” [20].)
Passing the query parameter ?enabled_only=true suppresses any private (non-CDN-

enabled) containers from appearing in the list. Thus, Cloud Files provides filtering support
to return only the list of containers that are CDN-enabled.
The list of CDN-enabled containers is returned in the response body, one container name
per line.
A list of containers is returned in the response body, one container per line.
The HTTP response status code is a value from 200 to 299, inclusive. A 200 (OK) code
returns if there are containers, and a 204 (No Content) code returns if there are no
containers.
To view the CDN container details, see Section 9.2.2, “List a CDN-Enabled Container's
Metadata” [89].
9.1.1.1. Request
This table shows the URI parameters for the List CDN-Enabled Containers Request:

This table shows the Query parameters for the List CDN-Enabled Containers Request:

enabled_only Int Set to true to return only CDN-enabled containers.
(Optional)
limit Int For an integer value n, limits the number of results to n values.
(Optional)
marker String Given a string value x, returns container names greater in value than
the specified marker. Only strings using UTF-8 encoding are valid.
(Optional) Using marker provides a mechanism to iterate through the entire list
of containers.
end_marker String Given a string value x, returns container names less in value than the
specified end marker. Only strings using UTF-8 encoding are valid.
(Optional)
format String Value of the serialized response format - either json or xml.
(Optional)
83
Developer Guide
Example 9.1. CDN-Enabled Containers List Request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?enabled_only=true
HTTP/1.1
Host: cdn.clouddrive.com
9.1.1.2. Response
Example 9.2. CDN-Enabled Containers List Response
HTTP/1.1 200 OK
Date: Thu, 08 Sep 2011 14:35:45 GMT
Content-Type: text/plain
images
movies
9.2. CDN Container Services

You can perform the operations in the following table on CDN-enbled containers in your
Cloud Files account.
When you CDN-enable a container, all the objects within it become available on the CDN.
Similarly, once a container is CDN-enabled, any objects added to it through the storage
service become CDN-enabled. After you CDN-enable a container, its publicly-available URI
can be found with the header X-Cdn-Uri, and its objects may be accessed at X-Cdn-
Uri/objectName. By knowing this pattern, you can pre-generate the URI for an object
before it is added to the container.
When you enable a container in the CDN service, you automatically generate URIs for
SSL and streaming usage. They are listed under the X-Cdn-Ssl-Uri and X-Cdn-
Streaming-Uri headers, respectively.
On August 13, 2012, the format of new CDN URIs changed in order to enhance
the security of the Content Delivery Network. Any URIs set in the older
format (http://c25810.r10.cf1.rackcdn.com/mydog.jpg) continue
to work. However, any newly generated CDN URIs have the new format:
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com/mydog.jpg.
Note on CDN Charges

Keep an eye on your CDN charges. When you CDN-enable a container, not
only can anyone view it, but anyone can link to it. We recommend that you
monitor your bandwidth usage and charges in the Cloud Control Panel. This
way, you know if someone is hot linking your content. For helpful instructions
for keeping yourself informed about your usage charges, see the Knowledge
Center article "Protect your Cloud Files CDN Bill from Unexpected Usage".
84
Developer Guide
For your own requests, you must use your own account information, authentication
token, and container name. You can check how to generate an authentication token in
Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token and
your account information are in the service catalog that is produced.

PUT v1/{account}/{container} Enables or disables a container for use with the CDN.
HEAD v1/{account}/{container}{?format} Gets a CDN-enabled container's metadata.
POST v1/{account}/{container} Updates the CDN-enabled container metadata.
85
Developer Guide
9.2.1. CDN-Enable and CDN-Disable a Container

PUT v1/{account}/{container} Enables or disables a container for use with the CDN.
Before a container can be CDN-enabled, it must exist in the storage system. To CDN-enable
the container, perform a PUT request against it using the publicURL noted in the service
catalog for Cloud Files during Authentication and set the X-CDN-Enabled header to
True.
Section 3.1.2, “Retrieving the Authentication Token” [10] provides an example of the

information in the service catalog for cloudfilesCDN.
When a container is CDN-enabled, any objects stored in it are publicly accessible over the
content delivery network by combining the container's CDN URI with the object name (X-
Cdn-Uri/objectName ).
Note
The examples in this guide use cdn.clouddrive.com for an endpoint
for operations against the CDN management service, but you should use
whatever your authentication request provides. For more information about
your authentication request, see Section 3.1, “Authentication” [10]. For more
information about service access endpoints, see Section 3.3, “Service Access
Endpoints” [20].
Any CDN-accessed objects are cached in the CDN for a specified amount of time called the
Time To Live (TTL). Each time the object is accessed after the TTL expires, the CDN refetches
and caches the object for the next TTL period.
You can specify the TTL for an object by including the HTTP header X-TTL:
integerSeconds . Setting the TTL is the same as setting the HTTP Expires and
Cache-Control headers for the cached object. The minimum TTL is 15 minutes (900
seconds), and the maximum is 50 years for a range of 900 to 1576800000 seconds.
However, setting a TTL for a long time does not guarantee that the content stays
populated on CDN edge servers for the entire period. The most popular objects stay cached
based on the edge location's logic.
Note
On August 13, 2012, the maximum TTL was set to 31536000 (one year). If you
set new TTL values to a greater time frame, your object still expires at the one-
year mark. However, if you already had a greater TTL value set on an object, it
will expire at the time you originally set.
A status code of 201 (Created) indicates that the container was CDN-enabled as requested.
If the container is already CDN-enabled, a 202 (Accepted) status code is returned, and
the TTL is adjusted. A status code of 204 (No Content) indicates the container was CDN-
enabled as requested, but has no content.
86
Developer Guide
In order to remove the container from the CDN, change the X-Cdn-Enabled header
to False, as in the request below. However, note that objects remain on the CDN edge
server and are served to the public until their TTL expires.
Note
The CDN URI is unique per container. After the container is CDN-enabled, you
can make a HEAD request to the Cloud Files CDN endpoint with the container
name to return the CDN URI in the X-Cdn-Uri header. You can use a cURL
request similar to the following example:
curl -I -H 'x-auth-token: yourAuthToken'
cloudFilesCDN:yourPublicURL/yourContainerName
Normal response codes: 200, 202, 204
9.2.1.1. Request
This table shows the Header parameters for the CDN-Enable and CDN-Disable a Container
Request:

X-Ttl Int Specifies the Time To Live in seconds for an object to be cached in the
CDN. The default value is 259200 seconds, or 72 hours.
(Optional)
X-Cdn-Enabled String Indicates if a container is CDN-enabled. Valid values are True and False.
(Optional)
This table shows the URI parameters for the CDN-Enable and CDN-Disable a Container
Request:

Example 9.3. CDN-Enable Container Request

UT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
X-Ttl: 259200
X-Cdn-Enabled: True
Example 9.4. CDN-Disable Container Request

X-CDN-Enabled: False
9.2.1.2. Response
This table shows the Header parameters for the CDN-Enable and CDN-Disable a Container
Response:
87
Developer Guide

X-Cdn-Uri Int Indicates the URI that you can combine with object names to serve
objects through the CDN.
(Optional)
Example 9.5. CDN-Enable Container Response

X-Cdn-Ssl-Uri: https://
83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.
r49.cf0.rackcdn.com
X-Cdn-Enabled: True
X-Log-Retention: False
X-Cdn-Streaming-Uri: http://
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.
rackcdn.
com
X-Trans-Id: tx82a6752e00424edb9c46fa2573132e2c
Content-Length: 0
88
Developer Guide
9.2.2. List a CDN-Enabled Container's Metadata

HEAD v1/{account}/{container}{?format} Gets a CDN-enabled container's metadata.
You can view CDN-enabled container details by performing a HEAD operation on a

container where the Host header value is one of the cdnCloudFiles service access
endpoints. (For a list of the endpoints, see Section 3.3, “Service Access Endpoints” [20]).
If the container is (or ever has been) CDN-enabled, the metadata is returned in headers in
the response for plain text, or in the response body for XML or JSON, if you request either
as your output format.
Note
Remember that your HEAD operation must be on the CDN host (i.e.,
cdn.clouddrive.com). Otherwise, you will see the metadata for your
private container as described in Section 5.1.3, “Get Account Metadata” [34].
A 204 (No Content) HTTP status code is returned if the account has no containers.
Otherwise, status code of 200 (OK) is returned.
9.2.2.1. Request
This table shows the URI parameters for the List a CDN-Enabled Container's Metadata
Request:

This table shows the Query parameters for the List a CDN-Enabled Container's Metadata
Request:

format String The optional format the returned information. Either XML or JSON.
(Optional)
Example 9.6. List a CDN-Enabled Container's Metadata Request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.
1
Example 9.7. List a CDN-Enabled Container's Metadata Request: JSON

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=
json
89
Developer Guide
Example 9.8. List a CDN-Enabled Container's Metadata Request: XML

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=
xml
9.2.2.2. Response
This table shows the Header parameters for the List a CDN-Enabled Container's Metadata
Response:

X-Cdn-Uri String The URI for downloading the object over HTTP. This URI can be
combined with any object name within the container to form the
(Required) publicly accessible URI for that object for distribution over a CDN
system.
X-Ttl Int The TTL value in seconds. The minimum TTL is 15 minutes (or 900
seconds), and the maximum is 50 years (1577836800 seconds).
(Required)
X-Cdn-Enabled Boolean True or False to indicate whether the container is currently marked to
allow public serving of objects through CDN
(Required)
X-Log-Retention Boolean True or False to indicate whether the CDN access logs should be
collected and stored in the Cloud Files storage system.
(Required)
X-Cdn-Ssl-Uri String The URI for downloading the object over HTTPS, using SSL. (The user
cannot have custom SSL certificates because our CDN partner does not
(Required) provide that feature.
X-Cdn-Streaming-Uri String The URI for video streaming that uses Adobe’s HTTP Dynamic
Streaming.
(Required)
X-Cdn-Ios-Uri String The URI for video streaming that uses Apple’s HTTP Live Streaming.
(Required)
Example 9.9. Get CDN-Enabled Container Metadata Request

83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.
ssl.cf0.rackcdn.com
X-Ttl: 259200
r49.cf0.rackcdn.com
X-Cdn-Enabled: True
X-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d
659bfc1ac1.r49.stream.cf0.rackcdn.com
Content-Length: 0
Example 9.10. List a CDN-Enabled Container's Metadata Response: JSON

HTTP/1.1 200 OK
90
Developer Guide
Date: Tue, 30 Oct 2012 17:57:28 GMT

Content-Length: 267
<account name="WidgetsRUs.button">
<container>
<name>images</name>
<cdn_enabled>True</cdn_enabled>
<ttl>86400</ttl>
<log_retention>True</log_retention>
<cdn_url>
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.
cf1.rackcdn.com
</cdn_url>
<cdn_ssl_url>
https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.ssl.
stg2.rackcdn.com
</cdn_ssl_url>
<cdn_streaming_url>
http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.
stream.cf0.rackcdn.com
</cdn_streaming_url>
</container>
</account>H
Example 9.11. List a CDN-Enabled Container's Metadata Response: XML

HTTP/1.1 200 OK
Date: Tue, 30 Oct 2012 14:41:29 GMT
Content-Length: 127
[
{"name":"test_container",
"cdn_enabled":"true",
"ttl":28800,
"log_retention":"true",
"cdn_uri":"http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com",
"cdn_ssl_uri":"https://
83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.ssl.stg2.rackcdn.com",
"cdn_streaming_uri":"http://
80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.rackcdn.com"}
]
91
Developer Guide
9.2.3. Update CDN-Enabled Container Metadata

POST v1/{account}/{container} Updates the CDN-enabled container metadata.
A POST operation against a CDN-enabled container adjusts the following metadata:
• X-Log-Retention
• X-Cdn-Enabled
• X-Ttl
returned if the requested container is not found.
9.2.3.1. Request
This table shows the Header parameters for the Update CDN-Enabled Container Metadata
Request:

X-Log-Retention Boolean True or False to indicate whether the CDN access logs should be
collected and stored in the Cloud Files storage system.
(Optional)
X-Cdn-Enabled Boolean True or False to enable or disable public sharing over the CDN. Keep
in mind that if you have content currently cached in the CDN, setting
(Optional) your container back to private will NOT purge the CDN cache. You
have to wait for the TTL to expire or purge the objects.
X-Ttl Int The TTL value in seconds. The minimum TTL is 15 minutes (or 900
seconds), and the maximum is 50 years (1577836800 seconds).
(Optional)
This table shows the URI parameters for the Update CDN-Enabled Container Metadata
Request:

Example 9.12. Update CDN-Enabled Container Metadata Request

1
X-Ttl: 86400
X-Cdn-Enabled: True
X-Log-Retention: True
92
Developer Guide
9.2.3.2. Response
Example 9.13. Update CDN-Enabled Container Metadata Response
X-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.
cf0.rackcdn.com
X-Cdn-Enabled: True
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.r49.stream.cf0.rackcdn.
com
Content-Length: 0
9.3. CDN Object Services

You can perform the operation in the following table on objects in your Cloud Files
containers.
• object, such as MyObject
For your own requests, you must use your own account information, authentication token,
container name, and object name. You can check how to generate an authentication token
in Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token
and your account information are in the service catalog that is produced.

DELETE v1/{account}/{object} Deletes CDN-enabled objects.
93
Developer Guide
9.3.1. Delete CDN Object

DELETE v1/{account}/{object} Deletes CDN-enabled objects.
When you find it necessary to remove a CDN-enabled object from public access before the
TTL expires, you can perform a DELETE operation against the object, or you can create a
support ticket to purge the entire container.
Note
You should limit object purges to situations where there could be serious
personal, business, or security consequences if it remained publicly accessible
on the CDN (for example, when someone publishs your company's quarterly
earnings too early).
Following are the ways you can purge objects from the CDN:
• By using DELETE in the API
You can manually purge CDN-enabled objects without having to wait for the TTL to
expire, and you can optionally be notified by email that the object has been purged.
However, you can only DELETE up to 25 objects per day using the API.
An attempt to delete more objects results in a 400 (Bad Request) status code with X-
Purge-Failed-Reason: You have the maximum number of daily object
purges.
If there is already a purge request in progress for an object, a 400 (Bad Request) status
code is returned with X-Purge-Failed-Reason: That object is already in
the queue to be purged.
• By creating a support ticket to purge an entire container
The 25-object limit does not apply when purging an entire container through Support.
Note
To prevent the container from going back to the CDN, first change the X-CDN-
Enabled flag to False as shown in Section 9.2.1, “CDN-Enable and CDN-
Disable a Container” [86]
The system purges the object from the CDN and sends an email to the indicated address or
addresses. If you want to notify more than one person about the deletion, you can enter a
comma-separated list of addresses. The email address is optional.
A status code of 204 (No Content) indicates success. Status code 404 (Not Found) indicates
that requested CDN-enabled object was not found. Status code 403 (Forbidden) indicates
that an authorization problem occurred.
The CDN URI is returned in the HTTP header X-Cdn-Uri.
94
Developer Guide
Purging objects may take a long time because there are so many edge servers around the
globe. Please be patient while waiting for a response.
Error response codes: itemNotFound (404), forbidden (403)
9.3.1.1. Request
This table shows the URI parameters for the Delete CDN Object Request:

Example 9.14. Delete CDN-enabled Object Request

DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
X-Purge-Email: [email protected], [email protected]
9.3.1.2. Response
Example 9.15. Delete CDN-Enabled Object Response
Date: Thu, 13 Jan 2010 18:57:07 GMT
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.
cf0.rackcdn.com
Content-Length: 0
95
Developer Guide
10. Additional CDN Services Information

The following sections provide additional information about working with the Cloud Files
CDN Services.
10.1. Purge CDN-Enabled Containers

For a container to be purged from the CDN, you can either wait for the TTL to expire,
or you can request that Rackspace remove, or purge, a CDN-enabled container from the
network. After you have made the request to Rackspace through a support ticket, the
system purges the object from the CDN, and sends an email to the address (or multiple
addresses) that you indicate through the ticket. The email address notification is optional.
Note
To prevent the container from going back to the CDN, first change the X-CDN-
Enabled flag to False as shown in Section 9.2.1, “CDN-Enable and CDN-
Disable a Container” [86].
10.2. CDN-Enabled Containers Served through SSL

A HEAD operation for a CDN-enabled container returns an SSL URI, X-Cdn-Ssl-Uri, in
addition to the other headers associated with CDN. This feature enables you to use https
protocol in URIs used for requesting objects stored in CDN-enabled containers.
returned if the requested container was not found. No content is returned.
Example 10.1. CDN-Enabled Container Metadata Request with SSL

1
Example 10.2. CDN-Enabled Container Metadata Response with SSL

ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.
cf0.rackcdn.com
X-Cdn-Enabled: True
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.rackcdn.
com
Content-Length: 0
96
Developer Guide
10.3. Streaming CDN-Enabled Containers

In addition to the other headers associated with CDN, a HEAD operation against a CDN-
enabled container returns the following streaming URIs to enable the streaming feature:
• X-Cdn-Streaming-Uri: specifies a URI for video streaming that uses Adobe’s HTTP
Dynamic Streaming
• X-Cdn-Ios-Uri: specifies the URI for video streaming that uses Apple’s HTTP Live
Streaming (see Section 10.4, “iOS Streaming” [97])
Streaming is a method of relaying data, such as video and audio material, over the network
as a steady continuous stream, allowing playback to proceed while subsequent data is
being received.
returned if the requested container was not found. No content is returned.
For information about streaming to iOS devices, see Section 10.4, “iOS Streaming” [97].
Example 10.3. CDN-Enabled Container Metadata Request with Streaming

Enabled
1
Example 10.4. CDN-Enabled Container Metadata Response with Streaming

Enabled
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Ios-Uri: http://fb1ca9de5ff9525ff6f8-64e65126753c56b595824f56d25789bb.
iosr.cf1.rackcdn.com
com
X-Cdn-Enabled: True
X-Cdn-Ssl-Uri: https://2cb7edde3eac1dd66ea4-64e65126753c56b595824f56d25789bb.
ssl.cf1.rackcdn.com
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.
cf0.rackcdn.co
Content-Length: 0
10.4. iOS Streaming
The Cloud Files CDN allows you to stream video to iOS devices without needing to convert
your video. Once you CDN-enable your container, you have the tools necessary for
97
Developer Guide
streaming media to multiple devices. To leverage this ability, you must check the client's
User Agent with JavaScript. An example of the User Agent check and how to use it is given
below.
First, CDN-enable your container. For instructions, see Section 9.2.1: “CDN-Enable and CDN-
Disable a Container”. Two streaming URIs are created - the container's streaming URI (X-
Cdn-Streaming-Uri) and its iOS streaming URI (X-Cdn-Ios-Uri). Perform a HEAD
request against the CDN-enabled container to view these URIs.
Second, link to your content in a HTML page using a <video> element. Set the SRC
attribute of the VIDEO element to the full streaming URI for your container plus the name
of your content. In the below example, the streaming video is MobyDick.mp4.
Example 10.5. HTML 5 Video Element

<video width=”640” height=”480” id="videotag">
<source src=”http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.
r49.stream.cf0.rackcdn.com/MobyDick.mp4” />
</video>
Third, add JavaScript to the <head> element of your HTML page to check if the User Agent
is an iOS device. If it is, the JavaScript should use the container's iOS streaming URI (x-Cdn-
Ios-Uri) instead of the regular streaming URI. The Cloud Files CDN delivers the properly
formatted content for iOS devices only when the iOS streaming URI is used. Here, the
JavaScript sets the SRC attribute of the <video> element videotag to the iOS Streaming
URI. Remember to add your content's name to the end of the iOS streaming URI.
Example 10.6. JavaScript for User Agent Check

<script type=”text/javascript”>
function isIOS(){
return ((navigator.userAgent.match(/iPhone/i)) ||(navigator.userAgent.
match(/iPod/i)) || (navigator.userAgent.match(/iPad/
i))) != null;
}
function init(){
if (isIOS()){
document.getElementById(“videotag”).src = “http://
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.
iosr.cf0.rackcdn.com/MobyDick.mp4”;
}
}
</script>
Finally, add init() to the <body> element of your HTML page to call the User Agent
check when the page loads.
Example 10.7. Load JavaScript in HTML page

<body onload=”init()”>
With these pieces of code in place, the proper content streams will be set for iOS devices.
98
Developer Guide
11. Static Websites Using CDN-Enabled

Containers
This chapter describes how to use your CDN-enabled containers to create static websites in
Cloud Files.
11.1. Create Static Website

You can use your Cloud Files account to create a static website. First, you must CDN-enable
a storage container. Any HTML or static web pages in the container become available
through a static website once you set the X-Container-Meta-Web-Index header to
index.html or another index page of your choice. You can also create subdirectories in
your website by creating pseudo directories, as outlined in Chapter 6, “Pseudo Hierarchical
Folders and Directories” [66]. Each pseudo directory becomes a subdirectory in the website.
The page you set for X-Container-Meta-Web-Index becomes the index page for every
subdirectory in your website. Each of your pseudo directories should contain a file with
that name. So, if you set X-Container-Meta-Web-Index to index.html, you should
have an index.html page in each pseudo directory. For example, suppose that you have
a subdir pseudo directory. If you do not have an index.html page in subdir, visits to
myhost/subdir/ return a status code 404 (Not Found).
You also have the option of displaying a list of HTML files in your pseudo directory,
instead of a web page. You do this by setting the X-Container-Meta-Web-Listings
header to True. If listings are enabled, you can add styles to your file list by setting X-
Container-Meta-Web-Listings-CSS to a style sheet. For example, setting X-
Container-Meta-Web-Listings-CSS: listing.css makes listings link to the
listing.css style sheet. To view the HTML elements to which you can add styles, use your
browser to view the HTML source on the listing page.
You can modify the Content-Type of directory marker objects by setting the
X-Container-Meta-Web-Directory-Type header. If this header is not set,
application/directory is used by default. Directory marker objects are 0-byte objects
that represent directories to create a simulated hierarchical structure.
The instructions below describe using a CNAME with your DNS Server (or name server). This
is the domain name of your site (such as www.rackspace.com). Your CNAME is set up with
your individual DNS Server. For more information about using CNAMES, see the Cloud DNS
Developer Guide at docs.rackspace.com. Once you have your CNAME established, set the
CNAME to your Cloud Files CDN URI to get your site up and running on the Web.
Set up a Static Website
The following list gives the step-by-step instructions for setting up a Static Website.
1. Create a container.
2. Upload your pages to a container.
99
Developer Guide
3. Set the index (or primary page) for your website by performing a POST to the header
X-Container-Meta-Web-Index on your website's container. See the example
below. (Remember to change the X-Auth-Token to your authentication token.) You
must use your storage URL and the container name to properly point to the container
(storageURL/containerName).
(You get your Auth token when you authenticate your session as shown in Section 3.1:
“Authentication”.)
4. CDN-enable your container as shown in Section 9.2.1: “CDN-Enable and CDN-Disable a

Container”.
5. Go to your domain host and set up a CNAME using your CDN URI (X-Cdn-Uri).
The CNAME is the domain or branded URI you use instead of the CDN URI. If you
need to find your CDN URI, perform a HEAD to cdn.clouddrive.com as shown in
Section 9.2.2: “List a CDN-Enabled Container's Metadata”.
6. To view your website online, visit your CDN URI or your CNAME domain.
Example 11.1. Set up Static Web

cURL -X POST -H "X-Container-Meta-Web-Index: index.html" -H "X-Auth-Token:
f064c46a782c444cb4ba4b6434288f7c" "https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_a55df/MyLibrary/"
After your container has an index page set and your domain host has your CNAME
recorded, your static website is ready.
Example 11.2. Container Setup for Static Website

container/index.html
container/page2.html
container/subdir/index.html
container/subdir/pageX.html
In the results below, the CNAME is myhost, and the X-Container-Meta-Web-Index is

set to index.html. The results on the right of the example are the pages that display in the
Web browser.
Example 11.3. Static Website Enabled Container Results

http://myhost Displays container/index.html
http://myhost/page2.html Displays container/page2.html
http://myhost/subdir Displays container/subdir/index.html
http://myhost/subdir/ Displays container/subdir/index.html
http://myhost/subdir/pageX.html Displays container/subdir/pageX.html
11.2. Set Error Pages for Static Website

You can create and set custom error pages for visitors to your website. To do this, set the
metadata header X-Container-Meta-Web-Error. Currently, only 401 (Unauthorized)
and 404 (Not Found) status codes are supported.
Error pages are served with the status code prepended to the name of the error page you
set. For instance, if you set X-Container-Meta-Web-Error to error.html, 401 errors
100
Developer Guide
display the page 401error.html. Similarly, 404 errors display 404error.html. You
must have both of these pages created in your container when you set the X-Container-
Meta-Web-Error metadata, or your site will display generic error pages.
Set the X-Container-Meta-Web-Error metadata once for your entire static website.
Example 11.4. Set Error Pages for Static Website Request

1
X-Container-Meta-Web-Error: error.html
Any class 200 status codes indicate success.
101
Developer Guide
12. Bulk Operations

This chapter describes bulk operations that are available with Cloud Files.
12.1. Bulk Importing of Data

If you have a very large amount of data to import into Cloud Files, bulk importing of
data is available. With bulk importing, you send a physical device containing your data
to Rackspace and Rackspace loads it directly into Cloud Files. By doing this, you avoid the
time and cost of uploading large amounts of data over the Internet. After the transfer is
complete, Rackspace either ships your device back to you, or destroys it after degaussing,
whichever you prefer.
Note
Bulk import is available for U.S. data centers only. However, if you have a need
for bulk importing in a data center outside of the U.S., contact Rackspace
support to see what other options you might have. They will be interested in
specifics like the amount of data you need to work with.
Rackspace accepts USB, SATA, and eSATA devices. Your file system can be NTFS, ext2,
ext3, ext4, or FAT32. Because Cloud Files does not use hierarchical directory structures,
nested sub-directories in your data are converted to object names. Your top-level folders
become containers, and nested directory names become part of the object names. For
instance, Chapter28/Ahab/ivoryleg results in a container named Chapter28 with an
object named Ahab/ivoryleg inside of it. For more information on simulating directory
structures in Cloud Files, see Chapter 6, “Pseudo Hierarchical Folders and Directories” [66].
To begin the bulk import process, contact Rackspace support technicians. You will be
assigned a migration specialist who can answer any questions you might have along the
way. You are notified when Rackspace receives your device, begins the data import,
completes data import, and ships back or destroys the device.
12.2. Extract Archive
An extract archive request expands tar files into a Cloud Files account. The request is a PUT
with the query parameter ?extract-archive=format specifying the format of archive
file. Accepted formats are tar, tar.gz, and tar.bz2.
Note
The bulk operation involves middleware that conducts many operations on a
single request.
For the PUT request, use the following URL:
/v1/AUTH_Account/$UPLOAD_PATH?extract-archive=tar.gz
UPLOAD_PATH is the location where the files are expanded and can specify any of the
following:
102
Developer Guide
• a container
• a pseudo directory within a container
• an empty string
If the UPLOAD_PATH is an empty string, Cloud Files automatically creates containers in

which to place the files. Files in the base directory of the tar file (that is, files that are not
in a folder of the unzipped tar file) are ignored.
The destination of a file in the archive is built as follows:
/v1/AUTH_Account/$UPLOAD_PATH/$FILE_PATH
FILE_PATH is the file name from the listing in the tar file.
You can create up to 1,000 new containers per extraction request. Also note that
only regular files are uploaded. Objects such as empty directories and symlinks are not
uploaded.
The responses from bulk operations are not like other Cloud Files responses because a
short request body sent from the client could result in many operations on the proxy server
and precautions need to be made to prevent the request from timing out due to a lack of
activity. To this end, the client always receives a 200 OK response, regardless of the actual
success of the call. The body of the response, which can be delivered over a greater amount
of time, must be parsed to determine the actual success of the operation. In addition, the
client may receive whitespace characters prepended to the response body while the proxy
server is completing the request.
The format of the response body defaults to text plain but can be either JSON or XML
depending on the Accept header. Acceptable formats are text/plain, application/
json, application/xml, and text/xml. The following example shows the response
body, formatted in JSON, from a successful request.
Example 12.1. Extract Archive Response

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
X-Trans-Id: txa7fd1603cfe04bdb920cd-005191226d
Date: Mon, 13 May 2013 17:27:10 GMT
{
"Number Files Created": 10,
"Response Status": "201 Created",
"Errors": [],
"Response Body": ""
}
The example that follows shows the response with errors.
Example 12.2. Extract Archive Response with Errors

103
Developer Guide
HTTP/1.1 200 OK
X-Trans-Id: tx9f12e16f047049cc91147-005191245f
Date: Mon, 13 May 2013 17:35:27 GMT
{
"Number Files Created": 10,
"Response Status": "400 Bad Request",
"Errors": [
[
"/v1/AUTH_test/test_cont/big_file.wav",
"413 Request Entity Too Large"
]
],
"Response Body": ""
}
The list of errors is a list of tuples in the form [objectPath, errorResponse].

The objectPath given is the full path of where the object was to be put. The
errorResponse is the failing HTTP status of the response for that individual PUT. After
1,000 errors, processing of the request ends, and the completed response is returned.
If all valid files were uploaded successfully, the Response Status in the response body is
201 Created. If any files failed to be created, the Response Status corresponds to the
subrequest's error. Possible codes are 400, 401, and 502. In both cases, the response body
specifies the number of files successfully uploaded and a list of the files that failed. (The
actual HTTP status code is always 200 OK, so the response code in the response body is the
one you should monitor.)
Note
If you send a Content-Type on the PUT request, the specified Content-
Type applies to every object in the archive. If you set Content-Type to
a blank string, Cloud Files determines the Content-Type based on the
individual file type. For example, if you have MIME type files, use a blank string
for Content-Type to set the MIME type for files within the archive.
12.3. Bulk Delete
Bulk Delete request deletes multiple objects or containers from an account with a single
request. A Bulk Delete request is a DELETE request with the query parameter ?bulk-
delete set. The Content-Type header of the request, if set, must be set to text/
plain. You should direct the request to the service endpoints in Section 3.3, “Service
Access Endpoints” [20]. The requests should be directed to the root of the service endpoint.
The body of the DELETE request a newline-separated list of URL-encoded objects to delete.
You can delete 10,000 objects per request.
Note
The bulk operation involves middleware that conducts many operations on a
single request.
The objects specified in the DELETE request body must be URL-encoded and in the form:
104
Developer Guide
/containerName/objectName
or for containers (which must be empty at time of delete)
/containerName
The response is similar to the extract archive responses in that every response will be 200
OK and the response body must be parsed for actual results. The following example shows
the response body, formatted in JSON, from a successful request.
Example 12.3. Bulk Delete Response

HTTP/1.1 200 OK
X-Trans-Id: tx52fe4601dde24e2b8e7cb-0051912ca8
Date: Mon, 13 May 2013 18:10:48 GMT
{
"Number Not Found": 1,
"Response Status": "200 OK",
"Errors": [],
"Number Deleted": 10,
"Response Body": ""
}
The example that follows shows the response with errors.
Example 12.4. Bulk Delete Response with Errors

HTTP/1.1 200 OK
X-Trans-Id: tx28552a8cd9cb441dad3ad-0051912d2d
Date: Mon, 13 May 2013 18:13:01 GMT
{
"Number Not Found": 0,
"Response Status": "400 Bad Request",
"Errors": [
[
"/v1/AUTH_test/non_empty_container",
"409 Conflict"
]
],
"Number Deleted": 0,
"Response Body": ""
}
If all items were successfully deleted (or did not exist), the status code is 200 OK. If any
failed to delete, the status code corresponds to the subrequest's error. Possible codes
are 400, 401, and 502. In all cases, the Response Body specifies the number of items
successfully deleted or not found as well as a list of those that failed. The return body is
105
Developer Guide
formatted in the way specified in the request's Accept header. Acceptable formats are
text/plain, application/json, application/xml, and text/xml.
The list of errors is a list of tuples in the form [objectPath, errorResponse]. The
objectRath is the full path of where the object (or container) was to be deleted. The
errorResponse is the failing HTTP status of the response for that individual DELETE.
106
Developer Guide
13. Public Access to Your Cloud Files

Account
This section describes ways that you can allow others to put or retrieve objects from your
Cloud Files account. With the methods described here, users do not need your password or
login information in order to have access to your account.
13.1. TempURL
The Temporary URL feature (TempURL) allows you to create limited-time Internet
addresses that allow you to grant limited access to your Cloud Files account. Using
TempURL, you can allow others to retrieve or place objects in your Cloud Files account for
a specified amount of time. Access to the TempURL is independent of whether or not your
account is CDN-enabled. And even if you do not CDN-enable a directory, you can still grant
temporary public access through a TempURL.
This feature is useful if you want to allow a limited audience to download a file from your
Cloud Files account or website. You provide a TempURL and after a specified time, no one
will be able to access that object using the TempURL. Or, if you want to allow others to
upload objects into your Cloud Files account, you can give them a TempURL. After the
specified time expires, no one will be able to upload to the address.
Additionally, you need not worry about time running out when someone downloads a
large object. If the time expires while a file is being retrieved, the download will continue
until it is finished. Only the link will expire.
When you create a TempURL, Cloud Files validates a GET-accessible or PUT-accessible URL,
which is time-limited.
Note
The TempURL is the same thing as TempURL Secret, and is set using the
TempURL metadata key described in the next section. The TempURL is the
actual URL.
13.1.1. Set Account TempURL Metadata Key

To create a TempURL, you must first set the metadata header X-Account-Meta-Temp-
Url-Key on your Cloud Files account to a key that only you know. This key can be any
arbitrary sequence as it is for encoding your account.
Once the key is set, you should not change it while you still want others to be able to access
your TempURL. If you change it, the TempURL becomes invalid (within 60 seconds, which is
the cache time for a key) and others will not be allowed to access it.
Example 13.1. Set Account Metadata Key for Public Access

X-Account-Meta-Temp-Url-Key: yourKey
107
Developer Guide
Any class 200 status code indicates success.
13.1.2. Create the TempURL

After the metadata is set, you must create an HMAC-SHA1 (RFC 2104) signature. When you
generate the TempURL, you determine which method of access you will grant users, GET
or PUT. You also determine the path to the object to which you are granting access. Lastly,
you set the time for your TempURL to expire in UNIX epoch notation.
In the following examples, a TempURL is generated for the object my_cat.jpg that will be
available for 60 seconds. The key in the example below is the X-Account-Meta-Temp-
Url-Key.
Example 13.2. Create TempURL (in python)
import hmac
from hashlib import sha1
from sys import argv
from time import time
if len(argv) != 5:
print 'Syntax: <method> <url> <seconds> <key>'
print 'Example: GET https://storage101.dfw1.clouddrive.com/v1/' \
'MossoCloudFS_12345678-9abc-def0-1234-56789abcdef0/' \
'container/my_cat.jpg 60 my_shared_secret_key'
else:
method, url, seconds, key = argv[1:]
method = method.upper()
base_url, object_path = url.split('/v1/')
object_path = '/v1/' + object_path
seconds = int(seconds)
expires = int(time() + seconds)
hmac_body = '%s\n%s\n%s' % (method, expires, object_path)
sig = hmac.new(key, hmac_body, sha1).hexdigest()
print '%s%s?temp_url_sig=%sAMP;temp_url_expires=%s' % \
(base_url, object_path, sig, expires)
Be certain to use the full URL to the object, just as you would with a normal request.
In this example, the signature might be da39a3ee5e6b4b0d3255bfef95601890afd80709

and the expire time might translate to 1323479485 because the signature and expires
completely depend on the time when the code runs. On your website, you would provide a
link to the URL below:
https://storage.clouddrive.com/v1/AUTH_account/container/my_cat.jpg?
temp_url_sig=da39a3ee5e6b4b0d3255bfef95601890afd80709&
temp_url_expires=1323479485
If you do not provide users with the exact TempURL, they get a 401 (Unauthorized) status
code. HEAD queries are allowed if GET or PUT are allowed.
Example 13.3. Create TempURL (in PHP)
108
Developer Guide
<?php
if ($argc != 5) {
echo "Syntax: <method> <url> <seconds> <key>";
echo "Example: GET https://storage101.dfw1.clouddrive.com/v1/" .
"MossoCloudFS_12345678-9abc-def0-1234-56789abcdef0/" .
"container/my_cat.jpg 60 my_shared_secret_key";
} else {
$method = $argv[1];
$url = $argv[2];
$seconds = $argv[3];
$key = $argv[4];
$method = strtoupper($method);
list($base_url, $object_path) = split("/v1/", $url);
$object_path = "/v1/$object_path";
$seconds = (int)$seconds;
$expires = (int)(time() + $seconds);
$hmac_body = "$method\n$expires\n$object_path";
$sig = hash_hmac("sha1", $hmac_body, $key);
echo "$base_url$object_path?" .
"temp_url_sig=$sig&temp_url_expires=$expires";
}
?>
Example 13.4. Create TempURL (in Ruby)
require "openssl"
unless ARGV.length == 4
puts "Syntax: <method> <url> <seconds> <key>"
puts ("Example: GET https://storage101.dfw1.clouddrive.com/v1/" +
"MossoCloudFS_12345678-9abc-def0-1234-56789abcdef0/" +
"container/path/to/object.file 60 my_shared_secret_key")
else
method, url, seconds, key = ARGV
method = method.upcase
base_url, object_path = url.split(/\/v1\//)
object_path = '/v1/' + object_path
seconds = seconds.to_i
expires = (Time.now + seconds).to_i
hmac_body = "#{method}\n#{expires}\n#{object_path}"
sig = OpenSSL::HMAC.hexdigest("sha1", key, hmac_body)
puts ("#{base_url}#{object_path}?" +
"temp_url_sig=#{sig}&temp_url_expires=#{expires}")
end
13.1.3. Override TempURL File Names

TempURLs support the filename query parameter to override the Content-Disposition
header and indicate to the browser a file name in which to save the file. In the following
example, you see the usual TempURL without the file name override.
109
Developer Guide
Example 13.5. TempURL without File Name Override
https://cf-cluster.example.com/v1/AUTH_account/container/object?temp_url_sig=
da39a3ee5e6b4b0d3255bfef95601890afd80709&temp_url_expires=1323479485
In the following example, you see &filename=bob.txt appended to the TempURL to

indicate to the browser to save the file as bob.txt:
Example 13.6. TempURL with File Name Override
https://cf-cluster.example.com/v1/AUTH_account/container/object?temp_url_sig=
da39a3ee5e6b4b0d3255bfef95601890afd80709&temp_url_expires=1323479485&filename=
bob.txt
13.2. FormPost
FormPost lets you offer your website audience a way to upload objects to your Cloud Files
account through a web form. FormPost works by translating a browser form request into a
object PUT in Cloud Files. Once you enable FormPost on your account, you need only create
the form in your website using the guidelines below.
As with all objects in Cloud Files, the object file size limit is 5 GB. If your users try to upload
an object larger than 5 GB, they will get a file size error.
13.2.1. Set Account Metadata Key

To allow FormPost actions on your Cloud Files account, you must first set the metadata
header X-Account-Meta-Temp-Url-Key on your Cloud Files account to a key that only
you know. This key can be any arbitrary sequence as it is for encoding your account.
Once the key is set, you cannot change it while you still want others to access your account.
If you change it, the actions from a FormPost become invalid (within 60 seconds, which is
the cache time for a key).
Example 13.7. Set Account Metadata Key for Public Access Request

X-Account-Meta-Temp-Url-Key: yourKey
Any class 200 status code indicates success.
13.2.2. Create the Form

To communicate between your website and your Cloud Files account, create a form using
the following format in your website:
110
Developer Guide
Example 13.8. Layout of Web Form
<form action="<CF-url>" method="POST" enctype="multipart/form-data">

<input type="hidden" name="redirect" value="<redirect-url>" />
<input type="hidden" name="max_file_size" value="<bytes>" />
<input type="hidden" name="max_file_count" value="<count>" />
<input type="hidden" name="expires" value="<unix-timestamp>" />
<input type="hidden" name="signature" value="<hmac>" />
<input type="file" name="file1" /><br />
<input type="submit" />
</form>
Required: Form action is the Cloud Files URL (CF-url) to the destination where files will
be uploaded. For instance, https://storage.clouddrive.com/v1/CF_xer7_34/
container. The name of each uploaded object will have the <CF-url> appended to the
front of it.
Note
You can also include a prefix to separate uploads, such as assigning each user
a certain prefix: https://storage.clouddrive.com/v1/CF_xer7_34/
container/user_prefix.
Required: The form method must be POST and the enctype must be set as multipart/
form-data.
Optional: The redirect attribute is the URL of the page that displays on your website
after the form processes. The URL will have status and message query parameters added
to it, indicating the HTTP status code for the upload (2xx indicates success) and a possible
message for further information if there is an error, such as “max_file_size exceeded”.
Note
Although redirect is optional for the form, it must be present in the HMAC
body.
Required: The max_file_size attribute must be included and specifies the maximum
size in bytes of a single file. However, the storage system maximum file size is 5 GB, so
max_file_size cannot exceed 5 GB.
Required: The max_file_count attribute indicates the maximum number of files that can
be uploaded with the form.
Required: The expires attribute is the Unix timestamp when the form is invalidated. This
gives your website users a limited time to have the form open. Time must be in Unix epoch
format.
Note
expires in the web form and expires in the HMAC must be the same.
Required: The signature attribute is the HMAC-SHA1 signature of the form. Here is
sample code for computing the signature in Python:
111
Developer Guide
Example 13.9. Generate Signature for Form Post
import hmac
from hashlib import sha1
from time import time
path = '/v1/account/container/object_prefix'
redirect = 'https://myserver.com/some-page'
max_file_size = 104857600
max_file_count = 10
expires = int(time() + 600)
key = 'mykey'
hmac_body = '%s\n%s\n%s\n%s\n%s' % (path, redirect,
max_file_size, max_file_count, expires)
signature = hmac.new(key, hmac_body, sha1).hexdigest()
Be certain to use the full path in your Cloud Files account, from the /v1/ onward.
The redirect value can be an empty string to indicate that no redirect is included on the
form.
The key value is the value of the X-Account-Meta-Temp-Url-Key header set for the
account.
The max_file_count value used to generate the signature must be the same as that
in the web form.
Required: The type="file" field defines the form file field. At least one entry is required
to allow your users to select and upload a file, but additional fields may be added for
multiple files. The number of entries should not, however, exceed the max_file_count.
Each type="file" field must have a different name.
Note
The type="file" field(s) must be at the end of the form code in order for
Cloud Files to process the uploads properly.
13.3. CORS
Cross-Origin Resource Sharing (CORS) is a mechanism to allow code running in a browser to
make requests to a domain other than the one from which it originated. CORS container
headers allow your users to upload files from one website, or origin, to your Cloud Files
account. When you set the CORS headers on your container, you provide Cloud Files with
the following information:
• Which sites can post to your account
• How often your container checks its allowed sites list
• What headers to expose to the browser in the request response
Note
You use CORS with:
112
Developer Guide
• FormPost (Section 13.2: “FormPost”) to enable your users to post to your site
• TempURL (Section 13.1: “TempURL ”) to limit how long users can use a given
URL
Cloud Files supports CORS requests to containers and objects. CORS metadata is held on the
container only. The values given apply to the container itself and all objects within it.
The following table lists the supported container headers.
Table 13.1. Supported CORS Container Headers

X-Container-Meta-Access-Control-Allow- Origins allowed to make Cross Origin requests,
Origin separated by a space when there are multiples.
X-Container-Meta-Access-Control-Max-Age Maximum age for the Origin to hold the preflight
results, in seconds (for example, 5, 10, or 1000).
X-Container-Meta-Access-Control-Expose- Headers exposed to the browser in the actual request
Headers response, separated by a space when there are
multiples.
Before a browser issues an actual request, it might issue a preflight request. The preflight
request is an HTTP OPTIONS call to verify that the origin is allowed to make the request.
The sequence of events is:
1. The browser makes an OPTIONS request to Cloud Files.
2. Cloud Files returns 200 or 401 to the browser based on the allowed origins.
3. If Cloud Files returns 200, the browser makes the actual request (DELETE, GET, HEAD,
POST, PUT) to Cloud Files.
When a browser receives a response to an actual request, it only exposes those headers
listed in the X-Container-Meta-Access-Control-Expose-Headers header. By
default, Cloud Files returns the following values for this header:
• the simple response headers as listed at www.w3.org/TR/cors/#simple-response-header/
• the headers ETag, X-Timestamp, X-Trans-Id
• all metadata headers (X-Container-Meta-* for containers and X-Object-Meta-*

for objects)
• headers listed in X-Container-Meta-Access-Control-Expose-Headers
To see some CORS Javascript in action, follow these steps:
1. Download the Example 13.11, “Test CORS Page” [114].
2. Host the page on a web server and take note of the protocol and hostname (origin) you
will be using to request the page, for example http://localhost.
3. Locate a container you would like to query. (Of course, the Cloud Files cluster hosting
this container should have CORS support.)
113
Developer Guide
4. Append the origin of the test page to the container’s X-Container-Meta-Access-

Control-Allow-Origin header, using a request similar to the following example.
Example 13.10. CORS POST Request
curl -X POST -H 'X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c' \

-H 'X-Container-Meta-Access-Control-Allow-Origin: http://localhost' \
http://192.168.56.3:8080/v1/AUTH_test/cont1
At this point, the container is accessible to CORS clients hosted on http://localhost.

Open the test CORS page in your browser and following these steps:
1. Populate the Token field.
2. Populate the URL filed with the URL of either a container or object.
3. Select the request method.
4. Hit Submit.
If the request succeeds, you should see the response header and body. If the request did
not succeed, the response status will be 0.
Example 13.11. Test CORS Page
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Test CORS</title>
</head>
<body>
Token<br><input id="token" type="text" size="64"><br><br>
Method<br>
<select id="method">
<option value="GET">GET</option>
<option value="HEAD">HEAD</option>
<option value="POST">POST</option>
<option value="DELETE">DELETE</option>
<option value="PUT">PUT</option>
</select><br><br>
URL (Container or Object)<br><input id="url" size="64" type=

"text"><br><br>
<input id="submit" type="button" value="Submit" onclick="submit(); return

false;">
<pre id="response_headers"></pre>
<p>
<hr>
<pre id="response_body"></pre>
<script type="text/javascript">
114
Developer Guide
function submit() {
var token = document.getElementById('token').value;
var method = document.getElementById('method').value;
var url = document.getElementById('url').value;
document.getElementById('response_headers').textContent = null;
document.getElementById('response_body').textContent = null;
var request = new XMLHttpRequest();
request.onreadystatechange = function (oEvent) {

if (request.readyState == 4) {
responseHeaders = 'Status: ' + request.status;
responseHeaders = responseHeaders + '\nStatus Text: ' +
request.statusText;
responseHeaders = responseHeaders + '\n\n' + request.
getAllResponseHeaders();
document.getElementById('response_headers').textContent =
responseHeaders;
document.getElementById('response_body').textContent =
request.responseText;
}
}
request.open(method, url);
request.setRequestHeader('X-Auth-Token', token);
request.send(null);
}
</script>
</body>
</html>
115
Developer Guide
14. Examples and Troubleshooting

This section introduces the cURL command-line utility and demonstrates interacting with
the REST interfaces through that utility.
Remember that object and container names must be URL-encoded and UTF-8 encoded.
Object names must be less than 1024 bytes in length after URL-encoding. For example, an
object name of C++final(v2).txt should be URL-encoded as C%2B%2Bfinal%28v2%29.txt
and therefore be 24 bytes in length rather than the expected 16.
Also, tokens expire after 24 hours. Be sure you request a new token programmatically only
when the one you have is expired.
14.1. Using cURL
cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets
you to transmit and receive HTTP requests and responses from the command line or a shell
script, which enables you to work with the API directly (without using one of the language-
specific APIs). It is available for Linux® distributions, Mac OS X® , and Windows®. For more
information about cURL, see http://curl.haxx.se.
The following cURL command-line options will be used
cURL Command-Line Options

-X METHOD Specify the HTTP method to request (GET, HEAD , DELETE, POST, PUT)
-D Dump HTTP response headers to stdout.
-H HEADER Specify an HTTP header in the request.
14.2. Authentication with cURL

In order to use the REST API, you will first need to obtain an authorization token, which will
need to be passed in for each request using the X-Auth-Token header.
The following examples demonstrate how to use cURL to obtain the authorization token
and the URL of the storage system. Note that your account may be based in either the
US or the UK. This is not determined by your physical location, but by the location of the
Rackspace retail site where the account was created.
This example uses the US-based URL https://identity.api.rackspacecloud.com/v2.0.
Example 14.1. cURL Authenticate Request with Username and API Key

Credentials and Response:JSON
curl -k -X POST https://identity.api.rackspacecloud.com/v2.0/tokens -d

'{ "auth":{ "RAX-KSKEY:apiKeyCredentials":{ "username":"yourUserName",
"apiKey":"yourApiKey" } } }' -H
"Content-type: application/json"
116
Developer Guide
{
"access": {
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://cdn1.clouddrive.com/
v1/yourAccountId",
"region": "DFW",
…
},
...
],
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"internalURL": "https://snet-storage101.dfw1.
clouddrive.com/v1/yourAccountId",
"publicURL": "https://storage101.dfw1.clouddrive.com/
v1/yourAccountId",
"region": "DFW",
…
},
...
],
"name": "cloudFiles",
"type": "object-store"
},
...
],
"token": {
"RAX-AUTH:authenticatedBy": [
"APIKEY"
],
"expires": "2013-10-29T05:36:28.683-05:00",
"id": "<auth_token>",
},
...
}
}
The storage URL, CDN management URL, and authentication token are returned in the
response. After authentication, you can use cURL to perform GET, HEAD, DELETE, POST
and PUT requests on the storage and CDN services.
While an authentication token lasts, you can continue to perform requests. However, once
a token expires, it will return an HTTP status code 401 (Unauthorized). Given that a token is
good for 24 hours, even long-running jobs do not need to re-authenticate on every request.
You will not need to request another X-Auth-Token again until the existing one expires.
At that point, you must obtain another authorization token. As a best practice example,
here is some pseudo code for re-authenticating. The best scalable process flow would be:
117
Developer Guide
1. Begin requests by going to identity.api.rackspace.com for an authentication token.
2. Send requests to the Cloud Files service access endpoints and set the X-Auth-Token
header with the authentication token obtained in Step 1.
3. Repeat step 2 using the same authentication token retrieved in Step 1 until either the
job finishes or you get a result code of 401 (Unauthorized).
• If the job finishes, you can allow the token to expire with no further action.
• If result code is 401, send a request to identity.api.rackspacecloud.com to get a new

authentication token to use in the Cloud Files X-Auth-Token header in your request.
A Python-based example of how to check for errors and re-authenticate upon receiving an
error can be found in the OpenStack Swift project in client.py, which is freely available.
14.3. Determining Storage Usage with cURL

A HEAD request can be sent to the storage service to determine how much data you
have stored in the system and the number of containers you are using. Use the -X switch
to specify the correct HTTP method and the -D to dump the HTTP response headers to
terminal output (stdout).
Example 14.2. cURL Get Storage Space
curl -X HEAD -D - \
-H "X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c" \
https://storage.clouddrive.com/v1/CF_xer7_343

X-Account-Object-Count: 4943
X-Account-Bytes-Used: 25603957646
X-Account-Container-Count: 151
Content-Length: 0
X-Trans-Id: txl5d1b08e3c1540at8cceda42acc723e4
Date: Wed, 07 Sep 2011 18:48:15 GMT
The HTTP request must include a header to specify the authentication token. The HTTP
headers in the response indicate the number of containers in this storage account and the
total bytes stored for the entire account.
14.4. Creating a Storage Container with cURL

Before uploading any data to Cloud Files, you must create a storage container. You do this
with a PUT request. cURL can be used for that, too.
Example 14.3. cURL Create Storage Container
curl -X PUT -D - \
118
Developer Guide
https://storage.clouddrive.com/v1/CF_xer7_343/images

Content-Length: 18
X-Trans-Id: txs56dc5b74f91419480ba485348057bfd
Date: Wed, 07 Sep 2011 18:52:30 GMT
Returning an HTTP status code of 201 (Created) indicates that the container was
successfully created.
14.5. Uploading a Storage Object with cURL

After creating a container, you can upload a local file. For this example, upload a
screenshot image. The -T switch specifies the full path to the local file to upload. Please
note that if you intend to distribute this object through the CDN you MUST make sure that
the object's Content-Type is set correctly. This is the mechanism by which a user's web
browser knows how to display the file or launch a helper application to view the file.
Example 14.4. cURL Upload Storage Object
curl -X PUT -T screenies/wow1.jpg -D - \

-H "ETag: 805120ec285a7ed28f74024422fe3594" \
-H "Content-Type: image/jpeg" \
-H "X-Object-Meta-Screenie: Mel visits Outland" \
https://storage.clouddrive.com/v1/CF_xer7_343/images/wow1.jpg

Date: Thu, 09 Aug 2012 17:03:36 GMT
Content-Length: 0
ETag: 805120ec285a7ed28f74024422fe3594
Content-Type: text/plain
14.6. CDN-Enabling the Container with cURL

After creating a container and storing a file in it, you can choose to share the file. Since the
data in Cloud Files is all private, you can share your screenshot through the CDN. To CDN-
enable a container, issue a PUT request against the CDN management service. The default
TTL is 72 hours and supports a minimum of 15 minutes (900 seconds) and a maximum of
50 years (1577836800 seconds). Note that the target URL specifies the CDN system, not the
authorization system.
Note
On August 13, 2012, the maximum TTL was set to 31536000 (one year). If
you set new TTL values to a greater time frame, your object will still expire at
119
Developer Guide
the one-year mark. However, if you already had a greater TTL value set on an
object, it will expire at the time you had originally set.
Example 14.5. cURL CDN-Enable Container
curl -X PUT -D - \
-H "X-CDN-Enabled: True" \
-H "X-TTL: 259200" \
https://cdn.clouddrive.com/v1/CF_xer7_343/images

83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.com
X-Ttl: 259200
r49.cf0.rackcdn.com
X-Cdn-Enabled: True
com
Content-Length: 0
When the container is CDN-enabled, the service returns its public URL in the X-CDN-URI
header of the response, plus the SSL URL in the X-Cdn-Ssl-Uri header of the response.
Now you can combine this URL with the object name to access the file through the CDN, or
use the https:// URL in combination with the object name to access the file over a secure
SSL connection through the CDN.
You can verify the CDN's cache settings that you specified with your TTL value by sending
a GET request to the object's CDN URL and viewing the response headers. The TTL value
you specify translates to the Expires and Cache-Control headers of the CDN's cached
Object.
The cURL command below issues a GET request which downloads the entire file but writes
it to /dev/null, a data sink that will not actually save the content to your local drive (this
convention is only valid on UNIX-like systems).
Example 14.6. cURL Download a File
curl -s -D - \
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.
rackcdn.com/wow1.jpg \
-O /dev/null
HTTP/1.1 200 OK
Date: Thu, 06 Aug 2009 01:40:12 GMT
Expires: Fri, 07 Aug 2009 01:40:12 GMT
120
Developer Guide
Last-Modified: Thu, 09 Jul 2009 17:14:46 GMT

Cache-Control: max-age=86400, public
ETag: b20237bff6828976d2eb348e1ca8adae
Connection: keep-alive
14.7. Other cURL Commands

You can issue any of the REST methods defined for Cloud Files with the cURL utility. For
example, you can use cURL to send POST and DELETE requests even though no specific
examples are provided.
It should be noted that generally each time curl is invoked to perform an operation,
a separate TCP/IP and SSL connection is created and thrown away. The language APIs,
however, are designed to re-use these connections between operations and therefore
provide much better performance. We recommend that you use one of the language APIs
in your production applications and limit curl to quick-and-easy testing/troubleshooting.
121
Developer Guide
Glossary
Account
The Cloud Files system is designed to be used by many different customers. Your user account is
your slice of the Cloud Files system. You must identify yourself with a valid user name and your
API access key. Once authenticated, your have full read/write access to the objects (files) stored
under your account.
Application program interface (API)

A set of routines, protocols, and tools for building software applications. A good API makes it
easier to develop a program by providing all the building blocks. A programmer then puts the
blocks together.
Authentication
Authentication requires getting an authentication token by using the Rackspace Cloud Identity
service. While the authentication token is valid (which in most cases is 24 hours), you must pass it
to Cloud Files to perform all Cloud Files operations.
CDN-enabled containers
To publish your data so that it can be served by Akamai's content delivery network (CDN), you
need to CDN-enabled the container that houses that data. When a container is CDN-enabled,
any files in the container are publicly accessible and do not require an authentication token for
read access. However, uploading content into a CDN-enabled container is a secure operation
and requires a valid authentication token. Each published container has a unique URL that
can be combined with its object name and openly distributed in web pages, emails, or other
applications. For example, a CDN-enabled container named photos can be referenced as
http://c0344252.cdn.cloudfiles.rackspacecloud.com. If that container houses an
image called cute_kids.jpg, that image can be served by Akamai's CDN with the full URL of
http://c0344252.cdn.cloudfiles.rackspacecloud.com/cute_kids.jpg.
Container
A storage compartment that provides a way for you to organize data. A container is similar to a
folder in Windows or a directory in UNIX. The primary difference between a container and these
other file system concepts is that containers cannot be nested.
Content delivery network (CDN)

A content delivery network (CDN) is a system of distributed servers (network) that deliver
webpages and other Web content to a user based on the geographic locations of the user, the
origin of the webpage, and a content delivery server.
Language-specific API
Language-specific APIs in several popular languages are available to help put Cloud Files in the
hands of developers. These APIs provide a layer of abstraction on top of the base REST API,
allowing programmers to work with a container and object model instead of working directly
with HTTP requests and responses.
Middleware
Software that connects two otherwise separate applications. For example, there are a number of
middleware products that link a database system to a Web server.
122
Developer Guide
Operations
Operations are the actions you perform against your account in Cloud Files, such as creating or
deleting containers, uploading or downloading objects, etc. Operations are performed via the
REST web service API or a language-specific API.
Permissions
There are no permissions or access-controls for containers or objects other than being split into
separate accounts. You must authenticate with a valid API access key, but once authenticated you
can create and delete containers and objects only within that account.
Private container
A private container is a container that is only accessible by the account holder.
Public container
A public container is a CDN-enabled container that is publicly accessible.
REST
REST, short for Representational State Transfer, is an architectural style for large-scale software
design.
123

Rackspace Cloud Files

Uploaded by

Copyright:

Available Formats

Rackspace Cloud Files

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Rackspace Cloud Files

Uploaded by

Copyright:

Available Formats

docs.rackspace.

Rackspace Cloud Files™ Developer Guide

5.3.6. Update Object Metadata ..................................................................... 64

14.7. Other cURL Commands ............................................................................... 121

5.44. Get Object Metadata Request .............................................................................. 62

13.3. Create TempURL (in PHP) ................................................................................... 108

Rackspace welcomes feedback, comments, and bug reports at

• RESTful web services

Rackspace also provides language-specific APIs in several popular programming languages.

1.2. Document Change History

• Updated the following object methods to include the X-Detect-Content-Type header

• PUT (Create or Update Object)

• POST (Update Object Metadata)

• COPY (Copy Object)

• Updated account information in Section 3.3, “Service Access Endpoints” [20] to show

• Added Section 3.4, “Cloud Files Service Contract Version” [22].

• Added Section 3.5, “Absolute Limits” [23].

• Added Section 3.6, “Request and Response Types” [23].

• Added Section 5.1.2, “Create or Update Account Metadata” [32].

• Added Section 5.1.4, “Delete Account Metadata” [36].

• Updated Section 2.2, “Authentication” [6] to include new references to additional

Revision Date Summary of Changes

• Updated Section 3.1, “Authentication” [10] to show information for Rackspace Identity

• Updated Section 13.3, “CORS ” [112].

• Added X-Container-Meta-Web-Listings, X-Container-Meta-Web-Listings-

• In Section 9.3, “CDN Object Services” [93] and Section 9.3.1, “Delete CDN

Revision Date Summary of Changes

1.4. Pricing and Service Level

• Section 2.1, “Accounts” [6]

• Section 2.4, “Containers” [6]

• Section 2.5, “Objects” [7]

For example, a CDN-enabled container named photos might be referenced as

3. General API Information

• If your account was created via http://www.rackspacecloud.com, it is a US-based

3.1.2. Retrieving the Authentication Token

Normal Status Code(s): 200, 203

Example 3.1. Auth Request: XML

POST /v2.0/tokens HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>

Example 3.2. Auth Request: JSON

POST /v2.0/tokens HTTP/1.1

The username supplied here is your common Rackspace Cloud username.

To find your API Key:

1. Log in to the Cloud Control Panel (https://mycloud.rackspace.com).

3. From the menu, select Account Settings.

6. Click Hide to hide the value of the API Key.

Example 3.3. Auth Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Example 3.4. Auth Response: JSON

This token can be presented to a service as evidence of authentication. Tokens are

Some services recognize specification of a tenant. If a service does recognize tenants,

3.2. Role Based Access Control

3.2.1. Assigning Roles to Account Users

• Create account users

• Assign roles to account users

• Delete roles from account users

3.2.2. Roles Available for Cloud Files

Table 3.1. Cloud Files Product Roles and Permissions

Table 3.2. Multiproduct (Global) Roles and Permissions

3.2.3. Resolving Conflicts Between RBAC Multiproduct vs.