Rackspace Cloud Files - Developer Guide

docs.rackspace.com/api

http://docs.rackspace.com/api

Rackspace Cloud Files™Developer Guide

February 21, 2014 API v1

ii

Rackspace Cloud Files™ Developer GuideAPI 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™ ApplicationProgramming 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 ORCOMPLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS ANDPRODUCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGEWITHOUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPTAS SET FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NOLIABILITY WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOTLIMITED 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 anylicense 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 andtrademarks used in this document are for identification purposes only and are property of their respective owners.



iii

Table of Contents1. Overview ..................................................................................................................... 1

1.1. Intended Audience ........................................................................................... 11.2. Document Change History ................................................................................ 21.3. Additional Resources ........................................................................................ 41.4. Pricing and Service Level ................................................................................... 5

2. Concepts ..................................................................................................................... 62.1. Accounts .......................................................................................................... 62.2. Authentication ................................................................................................. 62.3. Permissions ....................................................................................................... 62.4. Containers ........................................................................................................ 62.5. Objects ............................................................................................................. 72.6. Operations ....................................................................................................... 72.7. CDN-enabled Containers ................................................................................... 82.8. Language-Specific APIs ..................................................................................... 9

3. General API Information ........................................................................................... 103.1. Authentication ............................................................................................... 10

3.1.1. Geographic Endpoints .......................................................................... 103.1.2. Retrieving the Authentication Token .................................................... 10

3.2. Role Based Access Control .............................................................................. 193.2.1. Assigning Roles to Account Users ......................................................... 193.2.2. Roles Available for Cloud Files .............................................................. 193.2.3. Resolving Conflicts Between RBAC Multiproduct vs. Custom (Product-specific) Roles ................................................................................................ 203.2.4. RBAC Permissions Cross-reference to Cloud Files API Operations ............ 20

3.3. Service Access Endpoints ................................................................................. 203.4. Cloud Files Service Contract Version ................................................................ 223.5. Absolute Limits ............................................................................................... 233.6. Request and Response Types .......................................................................... 23

4. Overview of API Operations ...................................................................................... 245. API Operations for Storage Services ........................................................................... 26

5.1. Account Services ............................................................................................. 275.1.1. List Account Containers ....................................................................... 285.1.2. Create or Update Account Metadata ................................................... 325.1.3. Get Account Metadata ........................................................................ 345.1.4. Delete Account Metadata .................................................................... 36

5.2. Container Services .......................................................................................... 365.2.1. List Container Objects .......................................................................... 385.2.2. Create Container ................................................................................. 425.2.3. Delete Container .................................................................................. 445.2.4. Create or Update Container Metadata ................................................. 455.2.5. Get Container Metadata ...................................................................... 475.2.6. Delete Container Metadata .................................................................. 49

5.3. Object Services ............................................................................................... 505.3.1. Get Object Data .................................................................................. 515.3.2. Create or Update Object ...................................................................... 545.3.3. Delete Object ...................................................................................... 575.3.4. Copy Object ......................................................................................... 595.3.5. Get Object Metadata ........................................................................... 62



iv

5.3.6. Update Object Metadata ..................................................................... 646. Pseudo Hierarchical Folders and Directories ............................................................... 667. Additional Container Services Information ................................................................. 68

7.1. Container Quotas ........................................................................................... 687.2. Access Log Delivery ........................................................................................ 68

8. Additional Object Services Information ...................................................................... 708.1. Chunked Transfer Encoding ............................................................................ 708.2. Create Large Objects ...................................................................................... 70

8.2.1. Dynamic Large Object Creation ............................................................ 728.2.2. Static Large Object Creation ................................................................ 74

8.3. Enabling File Compression with the Content-Encoding Header ......................... 788.4. Enabling Browser Bypass with the Content-Disposition Header ........................ 788.5. Expiring Objects with the X-Delete-After and X-Delete-At Headers ....... 788.6. Object Versioning ........................................................................................... 79

9. API Operations for CDN Services ............................................................................... 829.1. CDN Account Services ..................................................................................... 82

9.1.1. List CDN-Enabled Containers ................................................................ 839.2. CDN Container Services .................................................................................. 84

9.2.1. CDN-Enable and CDN-Disable a Container ............................................ 869.2.2. List a CDN-Enabled Container's Metadata ............................................. 899.2.3. Update CDN-Enabled Container Metadata ........................................... 92

9.3. CDN Object Services ....................................................................................... 939.3.1. Delete CDN Object .............................................................................. 94

10. Additional CDN Services Information ....................................................................... 9610.1. Purge CDN-Enabled Containers ..................................................................... 9610.2. CDN-Enabled Containers Served through SSL ................................................. 9610.3. Streaming CDN-Enabled Containers ............................................................... 9710.4. iOS Streaming ............................................................................................... 97

11. Static Websites Using CDN-Enabled Containers ........................................................ 9911.1. Create Static Website .................................................................................... 9911.2. Set Error Pages for Static Website ............................................................... 100

12. Bulk Operations ..................................................................................................... 10212.1. Bulk Importing of Data ............................................................................... 10212.2. Extract Archive ........................................................................................... 10212.3. Bulk Delete ................................................................................................. 104

13. Public Access to Your Cloud Files Account .............................................................. 10713.1. TempURL .................................................................................................... 107

13.1.1. Set Account TempURL Metadata Key ............................................... 10713.1.2. Create the TempURL ........................................................................ 10813.1.3. Override TempURL File Names ......................................................... 109

13.2. FormPost .................................................................................................... 11013.2.1. Set Account Metadata Key ............................................................... 11013.2.2. Create the Form ............................................................................... 110

13.3. CORS .......................................................................................................... 11214. Examples and Troubleshooting .............................................................................. 116

14.1. Using cURL ................................................................................................. 11614.2. Authentication with cURL ........................................................................... 11614.3. Determining Storage Usage with cURL ........................................................ 11814.4. Creating a Storage Container with cURL ...................................................... 11814.5. Uploading a Storage Object with cURL ........................................................ 11914.6. CDN-Enabling the Container with cURL ....................................................... 119



v

14.7. Other cURL Commands ............................................................................... 121Glossary ....................................................................................................................... 122



vi

List of Figures4.1. Cloud Files System Interfaces .................................................................................. 25



vii

List of Tables3.1. Cloud Files Product Roles and Permissions ............................................................... 193.2. Multiproduct (Global) Roles and Permissions ........................................................... 203.3. Regionalized Service Endpoints for Storage Services ................................................ 203.4. Regionalized Service Endpoints for CDN Management Services ................................ 223.5. Absolute Limits ....................................................................................................... 235.1. Cloud Files Supported Range Formats ..................................................................... 517.1. Metadata Values for Setting Container Quotas ....................................................... 688.1. Comparison of Static and Dynamic Large Objects .................................................... 7213.1. Supported CORS Container Headers .................................................................... 113



viii

List of Examples3.1. Auth Request: XML ................................................................................................ 103.2. Auth Request: JSON ............................................................................................... 113.3. Auth Response: XML .............................................................................................. 123.4. Auth Response: JSON ............................................................................................. 143.5. Example Request URL (contract version in bold) ..................................................... 225.1. List Account Containers Request: XML .................................................................... 305.2. List Account Containers Request: JSON ................................................................... 305.3. List Account Containers Response: XML .................................................................. 315.4. List Account Containers Response: JSON ................................................................. 315.5. Create or Update Account Metadata Request ......................................................... 325.6. Create or Update Account Metadata Response ....................................................... 325.7. Get Account Metadata Request .............................................................................. 345.8. Get Account Metadata Response ............................................................................ 345.9. Delete Account Metadata Request ......................................................................... 365.10. Delete Account Metadata Response ..................................................................... 365.11. List Container Objects Request .............................................................................. 405.12. List Container Objects Request: XML ..................................................................... 405.13. List Container Objects Request: JSON .................................................................... 405.14. List Container Objects Response ............................................................................ 405.15. List Container Objects Response: XML ................................................................... 415.16. List Container Objects Response: JSON .................................................................. 415.17. Create Container Request ..................................................................................... 425.18. Create Container with Metadata Request ............................................................. 435.19. Create Container Response ................................................................................... 435.20. Create Container with Metadata Response ........................................................... 435.21. Delete Container Request ..................................................................................... 445.22. Delete Container Response ................................................................................... 445.23. Create or Update Container Metadata Request ..................................................... 455.24. Create or Update Container Metadata Response ................................................... 465.25. Get Container Metadata Request .......................................................................... 475.26. Get Container Metadata Response ....................................................................... 485.27. Delete Container Metadata Request ..................................................................... 495.28. Delete Container Metadata Response ................................................................... 495.29. Get Object Data Request ...................................................................................... 525.30. Get Object Data Request Using Range .................................................................. 525.31. Get Object Data Request Using Multiple Ranges ................................................... 525.32. Get Object Data Response .................................................................................... 525.33. Get Object Data Response Using Range ................................................................ 525.34. Get Object Data Response Using Multiple Ranges ................................................. 535.35. Create or Update Object Request ......................................................................... 555.36. Create or Update Object Response ....................................................................... 565.37. Delete Object Request .......................................................................................... 575.38. Delete Object Response ........................................................................................ 575.39. Copy Object Method 1 - Using PUT ....................................................................... 595.40. Copy Object Method 2 - Using COPY .................................................................... 595.41. Data Center Endpoints ......................................................................................... 605.42. Copy Object Request Using PUT ............................................................................ 615.43. Copy Object Request Using COPY ......................................................................... 61



ix

5.44. Get Object Metadata Request .............................................................................. 625.45. Get Object Metadata Response ............................................................................ 635.46. Update Object Metadata Request ......................................................................... 655.47. Update Object Metadata Response ....................................................................... 657.1. Example Access Log Entries .................................................................................... 698.1. Upload Unspecified Quantity of Content Request ................................................... 708.2. Upload Unspecified Quantity of Content Response ................................................. 708.3. Upload Segment of a Large Object Request ............................................................ 738.4. Upload Segment of a Large Object Response .......................................................... 738.5. Upload Next Segment of the Large Object Request ................................................. 748.6. Upload Next Segment of the Large Object Response ............................................... 748.7. Upload Manifest Request ....................................................................................... 748.8. Upload Manifest Response ..................................................................................... 748.9. Static Large Object Manifest List ............................................................................. 768.10. Request with Content-Encoding ............................................................................ 788.11. Request with Content-Disposition ......................................................................... 788.12. X-Delete-At Request .............................................................................................. 798.13. X-Delete-After Request ......................................................................................... 798.14. Object Versioning with cURL ................................................................................. 809.1. CDN-Enabled Containers List Request ...................................................................... 849.2. CDN-Enabled Containers List Response ................................................................... 849.3. CDN-Enable Container Request ............................................................................... 879.4. CDN-Disable Container Request .............................................................................. 879.5. CDN-Enable Container Response ............................................................................. 889.6. List a CDN-Enabled Container's Metadata Request .................................................. 899.7. List a CDN-Enabled Container's Metadata Request: JSON ......................................... 899.8. List a CDN-Enabled Container's Metadata Request: XML ......................................... 909.9. Get CDN-Enabled Container Metadata Request ....................................................... 909.10. List a CDN-Enabled Container's Metadata Response: JSON ..................................... 909.11. List a CDN-Enabled Container's Metadata Response: XML ...................................... 919.12. Update CDN-Enabled Container Metadata Request ............................................... 929.13. Update CDN-Enabled Container Metadata Response ............................................. 939.14. Delete CDN-enabled Object Request ..................................................................... 959.15. Delete CDN-Enabled Object Response ................................................................... 9510.1. CDN-Enabled Container Metadata Request with SSL .............................................. 9610.2. CDN-Enabled Container Metadata Response with SSL ............................................ 9610.3. CDN-Enabled Container Metadata Request with Streaming Enabled ...................... 9710.4. CDN-Enabled Container Metadata Response with Streaming Enabled .................... 9710.5. HTML 5 Video Element ......................................................................................... 9810.6. JavaScript for User Agent Check ........................................................................... 9810.7. Load JavaScript in HTML page .............................................................................. 9811.1. Set up Static Web ............................................................................................... 10011.2. Container Setup for Static Website ..................................................................... 10011.3. Static Website Enabled Container Results ............................................................ 10011.4. Set Error Pages for Static Website Request .......................................................... 10112.1. Extract Archive Response .................................................................................... 10312.2. Extract Archive Response with Errors .................................................................. 10312.3. Bulk Delete Response .......................................................................................... 10512.4. Bulk Delete Response with Errors ........................................................................ 10513.1. Set Account Metadata Key for Public Access ....................................................... 10713.2. Create TempURL (in python) .............................................................................. 108



x

13.3. Create TempURL (in PHP) ................................................................................... 10813.4. Create TempURL (in Ruby) .................................................................................. 10913.5. TempURL without File Name Override ................................................................ 11013.6. TempURL with File Name Override ...................................................................... 11013.7. Set Account Metadata Key for Public Access Request .......................................... 11013.8. Layout of Web Form .......................................................................................... 11113.9. Generate Signature for Form Post ....................................................................... 11213.10. CORS POST Request .......................................................................................... 11413.11. Test CORS Page ................................................................................................ 11414.1. cURL Authenticate Request with Username and API Key Credentials andResponse:JSON ............................................................................................................ 11614.2. cURL Get Storage Space ...................................................................................... 11814.3. cURL Create Storage Container ........................................................................... 11814.4. cURL Upload Storage Object ............................................................................... 11914.5. cURL CDN-Enable Container ................................................................................ 12014.6. cURL Download a File ......................................................................................... 120



1

1. OverviewRackspace Cloud Files™ is an affordable, redundant, scalable, and dynamic storage serviceoffering. The core storage system is designed to provide a secure, network-accessible wayto store an unlimited number of files. Each file can be as large as 5 gigabytes. You can storeas 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 distributecontent behind a Content Distribution Network. As a Cloud Files user, you get access tothis network automatically without having to worry about contracts, additional costs, ortechnical hurdles.

Cloud Files allows you to store and retrieve files and CDN-enabled content through a simpleWeb 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 integrateinto 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 [email protected].

1.1. Intended AudienceThis guide is intended to assist software developers who want to develop applicationsusing the Rackspace Cloud Files API. It fully documents the REST application programminginterface (API) that allows developers to interact with the storage and CDN componentsof the Cloud Files system. To use the information provided here, you should first have ageneral understanding of the Rackspace Cloud Files service and have access to an activeRackspace 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 Filesshould 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 CloudControl Panel provides an easy to use web-based interface for uploading and downloadingcontent 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-specificAPIs, refer to Rackspace Cloud SDKs Software Development Kit Guide. For information inthis book about language-specific APIs, refer to Language-Specific API Bindings.

http://www.rackspace.com/cloud/files/


http://www.rackspace.com/knowledge_center/article/best-practices-for-using-cloud-files

mailto:[email protected]

http://www.jungledisk.com/

http://www.fireuploader.com/

http://www.cyberduck.ch/

http://docs.rackspace.com/sdks/guide/content/intro.html



2

1.2. Document Change HistoryThis version of the Developer Guide replaces and obsoletes all earlier versions. The mostrecent 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 writeoperations, which is 100 operations per second per container.

• Updated the following object methods to include the X-Detect-Content-Type headerin 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) isignored, and Content-Type is guessed by using the Python mimetypes library based onthe object path.

• Reworked Chapter 5, “API Operations for Storage Services” [26] and Chapter 9, “APIOperations 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. Alsoadded tables showing the API operations at the beginning of each section that describes theoperations.

• 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 showMossoCloudFS_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 anauthentication 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 DynamicLarge Objects and Static Large Objects.

• Updated Section 12.2, “Extract Archive” [102] to include a note about using a blankContent-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, “ServiceAccess 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 thisdocument with references to the cloudFiles and cloudFilesCDN endpoints in theservice catalog based on use of Identity v2.0 rather than Identity v1.0.

• Updated Section 2.2, “Authentication” [6] to include new references to additionalinformation about the service access endpoints and the service catalog.



3


• Updated Section 14.2, “Authentication with cURL” [116] to show a cURL example forIdentity v2.0 only.

October 25, 2013 • Added Section 3.3, “Service Access Endpoints” [20], which includes all endpoints forCloud Files including the newest one in Hong Kong.

• Updated Section 3.1, “Authentication” [10] to show information for Rackspace Identityv2.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 StaticWebsite” [99].

July 18, 2013 • Clarified information about redirect and expires in Section 13.2.2, “Create theForm” [110].

July 2, 2013 • Corrected Example 7.1 (back to using Identity v1.0) in Section 14.2, “Authentication withcURL” [116] and added an example for Identity v2.0.

June 27, 2013 • In Section 3.1, “Authentication” [10], changed references for authentication to point tov2.0.

• In Section 14.2, “Authentication with cURL” [116], updated the example to show v2.0 forauthentication.

• In Section 9.3, “CDN Object Services” [93] and Section 9.3.1, “Delete CDNObject” [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 Practicesfor 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.





4


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 addingmore cross-references for finding language bindings.

November 15, 2011 • Revised information about how to perform a CDN purge, indicating you must contactsupport to request a container purge operation.

October 21, 2011 • Added more detail about reasons to perform a CDN purge, clarifying that it is not requiredfor 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 usinghttps protocol.

• Updated examples to contain SSL as appropriate.

February 25, 2011 • Added information about the edge purge capability for CDN-enabled containers andobjects.

February 18, 2011 • Fixed error in the header range example that stated first instead of last when fetching aportion 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 ResourcesYou can download the most current version of this document from the Rackspace Cloudwebsite 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 officialRackspace support channels, including Knowledge Center articles, forums, phone, chat, andemail.

For information about the Rackspace language-specific APIs that you can use for CloudFiles, refer to Rackspace Cloud SDKs Software Development Kit Guide. Each language-specific API includes its own documentation (either HTML, PDF, or CHM) including codesnippets and examples to help you get started. For information in this book about thelanguage-specific APIs, refer to Language-Specific API Bindings.

http://docs.rackspacecloud.com/files/api/cf-devguide-latest.pdf






5

1.4. Pricing and Service LevelCloud Files is part of the Rackspace Cloud and your use through the API will be billedaccording 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.

http://www.rackspace.com/cloud/public/files/pricing/

http://www.rackspace.com/information/legal/cloud/sla?page=files

http://www.rackspace.com/information/legal/cloud/sla?page=files



6

2. ConceptsCloud Files is not a file system in the traditional sense. You will not be able to map ormount 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 afew moments to review the key concepts listed below.

2.1. AccountsThe Cloud Files system is designed to be used by many different customers. Your useraccount is your portion of the Cloud Files system. You must identify yourself withyour Rackspace Cloud user name and API access key and once authenticated, youhave 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 APIaccess key.

2.2. AuthenticationSection 3.1, “Authentication” [10] describes how to authenticate against the RackspaceCloud Identity service to receive Cloud Files connection parameters and an authenticationtoken. 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 HTTPSrequest/response communication.

2.3. PermissionsIn Cloud Files, you have your own storage account and has full access to thataccount. You must authenticate with your credentials as described in Section 3.1,“Authentication” [10], but once authenticated you can perform all Cloud Filesoperations within that account.

2.4. ContainersA 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 primarydifference between a container and these other file system concepts is that containerscannot be nested. You can have up to 500,000 containers in your account. Data must bestored in a container so you must have at least one container defined in your account priorto uploading data.

If you expect to write more than 100 objects per second to a single container, werecommend organizing those objects across multiple containers to improve performance.

https://cart.rackspace.com/cloud/?cp_id=cloud_files

https://cart.rackspace.com/cloud/?cp_id=cloud_files

http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Overview-d1e65.html



7

The only restrictions on container names is that they cannot contain a forward slash (/) andmust be less than 256 bytes in length. Note that the length restriction applies to the nameafter it has been URL-encoded. For example, a container name of Course Docs would beURL-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 AccessEndpoints” [20] for a list.) However, in order to lower your costs, you should createyour most served containers in the same data center as your server. Otherwise, you willbe billed for external bandwidth charges. Note that this is true when computations areperformed on objects but is not true for static content served to end users directly.

2.5. ObjectsObjects are the basic storage entities in Cloud Files. They represent the files and theiroptional 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 theminto 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 lengthafter 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 ratherthan 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 ofsegmentation. Segments of the larger object are uploaded and a special manifest file iscreated 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 thesegments.

For metadata, you should not exceed 90 individual key/value pairs for any one object andthe total byte length of all key/value pairs should not exceed 4KB (4096 bytes).

2.6. OperationsOperations are the actions you perform within your account, such as creating or deletingcontainers or uploading or downloading objects. The full list of operations is given inChapter 5, “API Operations for Storage Services” [26]. The operations are thendescribed 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 SDKsSoftware Development Kit Guide.)





8

Important

All operations must include a valid authorization token.

2.7. CDN-enabled ContainersCDN-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 anauthorization token for read access. However, uploading content into a CDN-enabledcontainer 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 namesand openly distributed in web pages, emails, or other applications.

For example, a CDN-enabled container named photos might be referenced ashttp://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.rackcdn.com. If that container houses a screenshot calledwow1.jpg, that image can be served by a CDN with the full URL ofhttp://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 Filesstorage system. The copy is cached in a CDN and served from there for all subsequentrequests for a configurable cache time to live (TTL) value. Setting the TTL of a CDN-enabledcontainer translates to setting the Expires and Cache-Control HTTP headers. Notethat extremely long TTL values do not guarantee that an object is served from a CDN edgelocation. When the TTL expires, the CDN checks Cloud Files to ensure that it has the mostup-to-date content. A purge request forces the CDN to check with Cloud Files for the mostup-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 maximumvalues, see Section 9.3, “CDN Object Services” [93].

Containers tracked in the CDN management service are completely separate and distinctfrom 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 thatability.

However, for the content to be served from the CDN, the container names MUST match inboth 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 tocreate a container called images in the storage service.



9

2.8. Language-Specific APIsLanguage-specific APIs in several popular languages are available to help put Cloud Files inthe hands of developers. These language-specific APIs provide a layer of abstraction on topof the base REST API, allowing programmers to work with a container and object modelinstead of working directly with HTTP requests and responses. The language-specific APIsare free to download, use, and modify. They are licensed under the MIT license as describedin the COPYING file packaged with each API. If you make any improvements to an API, youare encouraged (but not required) to submit those changes back to Rackspace.

Detailed information about the language-specific APIs is in the Rackspace Cloud SDKsSoftware Development Kit Guide. If you have changes that you would like to see in theCloud File language-specific APIs, email them to [email protected]. Make sure toindicate 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 answerany questions during development, host your code if you like, and give you full credit foryour work.



mailto:[email protected]



10

3. General API InformationThe information in this chapter is relevant to all Cloud Files API operations. For informationabout a specific API operation, see later chapters.

3.1. AuthenticationEvery REST request against the Cloud Files service requires the inclusion of a specificauthorization token, supplied by the X-Auth-Token HTTP header. Customers obtain thistoken by first using the Rackspace Cloud Authentication Service and supplying a valid username and API access key.

3.1.1. Geographic EndpointsThe Rackspace Cloud Authentication Service serves as the entry point to all RackspaceCloud 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 yourphysical location but by the location of the Rackspace retail site that was used to createyour account.

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

• 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 ateither site to ask for help.

3.1.2. Retrieving the Authentication TokenPOST 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 ofregional cloud endpoints. The sample requests and responses in this section illustratea general case. In your authentication request, use your own credentials rather thanthe sample values shown here for username and apiKey. When you authenticatesuccessfully, the response to your authentication request will include a catalog of theservices to which you have subscribed rather than the sample values shown here.

Example 3.1. Auth Request: XML

https://identity.api.rackspacecloud.com/v2.0/

https://lon.identity.api.rackspacecloud.com/v2.0/

http://www.rackspacecloud.com

http://www.rackspace.co.uk



11

POST /v2.0/tokens HTTP/1.1User-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.6Host: identity.api.rackspacecloud.comAccept: application/xmlContent-Type: application/xmlContent-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.1User-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.6Host: identity.api.rackspacecloud.comAccept: application/jsonContent-Type: application/jsonContent-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 fieldand click Show.

5. Copy the value of the API Key and paste it into a text editor of your choice.

https://mycloud.rackspace.com



12

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

You also need your cloud account number. In the documentation, the accountnumber is often referred to as your tenant name or tenant ID (technically, the ID isdifferent from the name, but at Rackspace, they are the same thing). Together, threecomponents—your username, your API Key, and your tenant ID or cloud accountnumber—form the authentication credentials that are required to connect to theRackspace 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 oraccount number is in parentheses just to the right of your username.

Note

For Cloud Files, the information used in place of the account number withthe API operations is the MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee information found in service catalog of yourauthentication response, rather than the account number found in theCloud Control Panel, as described above.

Example 3.3. Auth Response: XML

HTTP/1.1 200 OKContent-Type: application/xml; charset=UTF-8Content-Length: 477Date: 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"/>



13

</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" tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"/> <endpoint region="ORD" tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" 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>



14

Example 3.4. Auth Response: JSON

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8Content-Length: 477Date: 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.rackspacecloud.com/v1.0/1100111", "region": "ORD", "tenantId": "1100111" } ], "name": "cloudDatabases", "type": "rax:database" }, { "endpoints": [ { "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/1100111", "region": "DFW", "tenantId": "1100111" }, {



15

"publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1100111", "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",



16

"internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",

"region": "DFW" }, { "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", "region": "ORD" } ],

"name": "cloudFiles",

"type": "object-store" }, { "endpoints": [ { "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "publicURL": "https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "region": "DFW" }, { "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-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-basedaccounts. If you authenticate against the UK-endpoint for auth, you will see theservice catalog information for UK-based accounts.



17

In XML responses only, a list of namespaces identifies API extensions that addfunctionality to the core API.

This token can be presented to a service as evidence of authentication. Tokens arevalid 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 willautomatically become invalid. A token may be manually revoked before the timeidentified by the expires attribute. The expires attribute predicts a token'smaximum 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 betweenmultiple endpoints associated with a service in the user's catalog, the endpoint for theuser's default region will be selected if it is available. In this example, the user's defaultregion is DFW and several of the services in the catalog offer endpoints in that regionand the ORD region. The user's work will be directed to the DFW region wheneverpossible.

Users can be assigned multiple roles, with each role providing specific privileges.In this example, jsmith is the administrative user for the account, holding thefully-privileged identity:admin role. Other users might hold other roles withdifferent privileges. Roles need not be associated with actual job functions such asAdministrator, Operator, Developer, Tester, or Trainer.

The service catalog lists the services you can access. In this example, the user can accessone database service, one loadbalancing service, two compute services (Cloud ServersOpenStack and Cloud Servers), two object storage services (Cloud Files ContentDistribution Network (CDN), and Cloud Files), and one DNS service. The cataloglisting for each service provides at least one endpoint URL for that service. Otherinformation, such as regions, versions, and tenants, is provided if it's relevant to thisuser's access to this service.

The service type attribute identifies services that perform similar functions, whateverthose services might be named. In this example, the services named cloudServers andcloudServersOpenstack are both identified as type="compute", identifying them ascompute 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 multipleendpoints of the same service type exist in the same region, use servicename as the tiebreaker.

The service name attribute identifies each unique service in the catalog. Once a serviceis created, its name does not change. However, new services of the same service typemay be added to the catalog with new names.

Important

If you are programmatically parsing an authentication response, useservice type rather than service name as the basis for determining whether



18

a user has access to a particular kind of service. Service type is stable acrossall releases. New service types may be developed, but existing service typesare not renamed. In this example, type="compute" identifies all theavailable compute services, one of which is named cloudServers and one ofwhich is named cloudServersOpenStack. New compute service names maybe added in future releases. Whatever the compute services are named,you can always recognize them by parsing for type="compute" in theauthentication response's service catalog.

A service may expose endpoints in different regions. Regional endpoints allow clientsto provision resources in a manner that provides high availability.

Some services are not region-specific. These services supply a single non-regionalendpoint 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 aboutwhether and how to specify a tenant, check the documentation for the service you areusing.

An endpoint can be assigned public and internal URLs. A public URL is accessible fromanywhere. Access to a public URL usually incurs traffic charges. Internal URLs areonly accessible to services within the same region. Access to an internal URL is free ofcharge.

Authentication tokens are typically valid for 24 hours. Applications should be designed tore-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.

Important

If you are programmatically parsing an authentication response, please beaware that service names are stable for the life of the particular service andcan be used as keys. You should also be aware that a user's service catalog caninclude multiple uniquely-named services which perform similar functions. Forexample, cloudServersOpenStack is the OpenStack version of compute whereascloudServers is the legacy version of compute. The same user can have accessto both services. In Auth 2.0, the service type attribute can be used as a key bywhich to recognize similar services.

Tip

Beginning with Auth 2.0, the service catalog includes a service type attribute toidentify services that perform similar functions but have different names. Forexample, type="compute" identifies compute services such as cloudServersand cloudServersOpenStack. Some developers have found the service typeattribute to be useful in parsing the service catalog. For additional informationon Auth 2.0 (also known as the Cloud Identity Service), refer to the CloudIdentity Client Developer Guide at http://docs.rackspace.com/.

Cloud Files service endpoints are published in the service catalog in the Auth responsewith the account information, which is a required element of the service endpoints. Theexamples shown here are for authentication for US customers. Customers with UK-based

http://docs.rackspace.com



19

accounts will see different values in the service catalog. Refer to Section 3.3, “Service AccessEndpoints” [20] for more information about service endpoints.

3.2. Role Based Access ControlRole Based Access Control (RBAC) restricts access to the capabilities of Rackspace Cloudservices, including the Cloud Files API, to authorized users only. RBAC enables RackspaceCloud customers to specify which account users of their Cloud account have access to whichCloud 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 certainoperations in the Cloud Files API – create, read, update, delete – are assigned to specificroles, and these roles can be assigned by the Cloud account admin user to account users ofthe account.

3.2.1. Assigning Roles to Account Users

The account owner (identity:user-admin) can create account users on the account andthen assign roles to those users. The roles grant the account users specific permissions foraccessing the capabilities of the Cloud Files service. Each account has only one accountowner, and that role is assigned by default to any Rackspace Cloud account when theaccount is created.

See the Cloud Identity Client Developer Guide for information about how to perform thefollowing 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 rolesbecause 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. Thefollowing 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 Deletepermissions in Cloud Files, where access is granted.

object-store:observer This role provides Read permission in Cloud Files, whereaccess is granted.

Additionally, two multiproduct roles apply to all products. Users with multiproductroles inherit access to future products when those products become RBAC-enabled. Thefollowing table describes these roles and their permissions.

http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/POST_addUser_v2.0_users_User_Calls.html

http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/PUT_addUserRole_v2.0_users__userId__roles_OS-KSADM__roleId__Role_Calls.html

http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/DELETE_deleteUserRole_v2.0_users__userId__roles_OS-KSADM__roleId__Role_Calls.html



20

Table 3.2. Multiproduct (Global) Roles and Permissions

Role Name Role Permissions

admin This role provides Create, Read, Update, and Delete permissions in allproducts, 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 isimportant to understand how any potential conflicts among these roles are resolved. Whentwo roles appear to conflict, the role that provides the more extensive permissions takesprecedence. 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 inthe Control Panel are resolved:

Permission Configuration View of Permissionin the Control Panel

Can the User Perform Product AdminFunctions in the Control Panel?

User is assigned the following roles:multiproduct observer and Cloud Filesadmin

Appears that the user has only themultiproduct observer role

Yes, for Cloud Files only. The user hasthe observer role for the rest of theproducts.

User is assigned the following roles:multiproduct admin and Cloud Filesobserver

Appears that the user has only themultiproduct admin role

Yes, for all of the products. The CloudFiles observer role is ignored.

3.2.4. RBAC Permissions Cross-reference to Cloud Files APIOperations

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

3.3. Service Access EndpointsCloud Files is a regionalized service. You can create your Cloud Files containers in anyRackspace data center. The user of the service is therefore responsible for appropriatereplication, caching, and overall maintenance of Cloud Files data across regional boundariesto other Cloud Files servers.

The endpoints to use for the storage service component of your Cloud Files API calls aresummarized in the table below.

Table 3.3. Regionalized Service Endpoints for Storage Services

Region Endpoint

https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Chicago (ORD)

https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Dallas/Ft. Worth (DFW) https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

http://www.rackspace.com/knowledge_center/article/permissions-matrix-for-role-based-access-control-rbac



21

Region Endpoint

https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

https://storage101.hkg1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Hong Kong (HKG)

https://snet-storage101.hkg1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

https://storage101.lon3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

London (LON)

https://snet-storage101.lon3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

https://storage101.iad3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Northern Virginia (IAD)

https://snet-storage101.iad3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

https://storage101.syd2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Sydney (SYD)

https://snet-storage101.syd2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Replace the sample MossoCloudFS information in the table above with the actualMossoCloudFS information returned as part of the authentication service response. Youwill find this after the final '/' in the publicURL field and the internalURL field in thecloudFiles section of the service catalog returned by the authentication response. Formore information about the account number, see the sample authentication request andresponse in Section 3.1.2, “Retrieving the Authentication Token” [10] as well as theCloud 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, usingthe ServiceNet endpoint in the same data center has no network costs and provides a fasterconnection. ServiceNet endpoints are prefixed with snet- in Table 3.3, “RegionalizedService Endpoints for Storage Services ” [20]. ServiceNet is the data center internetnetwork. 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 mustuse a public endpoint to connect. In your authentication response, public endpoints arelisted as publicURL. If you are working with servers in multiple data centers or have amixed environment where you have servers in your data centers and in Rackspace datacenters, use a public endpoint because it is accessible from all the servers in the differentenvironments.

Note

In order to avoid external bandwidth charges, your containers and servers mustbe in the same data center.

You might find it useful to locate your objects in more than one data center tokeep track of your data and backups. Specifically, if you serve an audience in a

https://mycloud.rackspace.com/



22

particular region, you might find it helpful to locate your Cloud Files objects asclose to that region as possible.

The endpoints to use for the CDN management service component of your Cloud Files APIcalls are summarized in the table below.

Note

If your audience is world wide, you might consider using the Akamai ContentDelivery Network (CDN). The CDN speeds your content delivery because it iscached at edge locations around the globe, rather than being served from asingle origin server. You can learn more about CDN-enabling your containers inSection 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-cccc-dddd-eeeeeeeeeeee/

Hong Kong (HKG) https://cdn6.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

London (LON) https://cdn3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Northern Virginia (IAD) https://cdn5.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Sydney (SYD) https://cdn4.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

As with the storage component service, replace the sample MossoCloudFS informationwith the actual MossoCloudFS information returned as part of the authentication serviceresponse. 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 bythe authentication response.

3.4. Cloud Files Service Contract VersionThe 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. Therequested contract version is included in all request URIs. Different contract versions of theAPI may be available at any given time and are not guaranteed to be compatible with oneanother.

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.



23

3.5. Absolute LimitsAbsolute limits are fixed. Absolute limits control the total number of specific objects thatthe 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 atone time

10,000 containers

Pseudo hierarchical folders anddirectories

Simulated hierarchical structure within a singlecontainer by adding forward slash characters (/) inthe object name

No limit

Container and object metadatalimits

Maximum metadata limits 4096 bytes maximum overallmetadata, with 90 distinctmetadata items at themost. Each may have a 128character name length witha 256 max value lengtheach.

Number of object segments perStatic Large Object (SLO)

Maximum number of object segments per SLO 1,000 object segments

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 singlerequest

5 GB (For larger files, seeSection 8.2.2, “Static LargeObject Creation” [74])or Section 8.2.1,“Dynamic Large ObjectCreation” [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 secondper 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 forthe container to 100 operations per second.

100 operations per second

3.6. Request and Response TypesYou specify the request format using the Content-Type header. The Cloud Files APIsupports both the JSON (application/json) and XML (application/xml) dataserialization formats, as well as other formats such as text/plain, text/xml, andtext/html along with video, audio, and image types. For pseudo hierarchical foldersand directories, application/directory might be used.

You specify the response format in requests by using the Accept header. The Cloud FilesAPI supports both the JSON (application/json) and XML (application/xml) dataserialization formats, as well as other formats such as text/plain and text/xml .



24

4. Overview of API OperationsThe Cloud Files API is implemented as a set of RESTful web services. All authenticationand container/object operations can be performed with standard HTTP calls. For moreinformation 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 bindingthat performs the URL-encoding on your behalf. If so, do not URL-encode before calling theAPI binding, or you will double-encode container and object names. The length restrictionsshould 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 inthe HTTP header X-Auth-Token. Clients obtain this token, along with the Cloud FilesURIs, by first using the Rackspace authentication service and supplying a valid user nameand 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 (seeSection 3.1.2, “Retrieving the Authentication Token” [10]) manages the data storage inthe 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 featureof Cloud Files.

http://en.wikipedia.org/wiki/Representational_State_Transfer



25

In the following sections, the purpose of each HTTP method depends upon which servicethe call is made against. For example, a PUT request against one of the cloudFilesendpoints can be used to create a container or upload an object, while a PUT requestagainst 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 simplycreate a container and mark it public and handle calling the appropriate back-end servicesby using the appropriate REST APIs.

Note

All requests to authenticate and operate against Cloud Files are performedusing SSL over HTTP (HTTPS) on TCP port 443.

The following diagram illustrates the various system interfaces and the ease with whichcontent can be distributed over the CDN. The process is simple: authenticate, create acontainer, upload objects, mark the container as public, and begin serving that contentfrom a powerful CDN.

Note

Marking the container as public simply means enabling the container to bedistributed over the CDN. A CDN-enabled container is publicly accessible.

Figure 4.1. Cloud Files System Interfaces

1 . Aut hent icat e

2 . Creat e Cont a iner and Upload Object s

3 . M ark Cont a iners Public

CDN M anagem entService

St orageService

Rackspace Cloud Aut hent icat ion

Service

4 . Serve Cont ent



26

5. API Operations for Storage ServicesThis 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 theservice catalog obtained during successful authentication. (For more information, seeSection 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 storagesystem:

• Section 5.1, “Account Services” [27] describes operations that you can perform at theaccount level of the storage system.

• Section 5.2, “Container Services” [36] describes operations that you can perform oncontainers.

• Section 5.3, “Object Services” [50] describes operations that you can perform onobjects.

Method URI Description

Account Services

GET v1/{account}{?limit,marker,end_marker,format}

Lists storage containers sorted by name.

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,marker,end_marker,prefix,format,delimiter,path}

Lists the objects stored in the container.

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 associatingcustom 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 objectsin the container and the total bytes for all objects stored inthe 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 aspecified object.



27


DELETE v1/{account}/{container}/{object} Permanently deletes an object from the Cloud Filesstorage system. (You can use COPY and then DELETE toeffectively move an object.)

COPY v1/{account}/{container}/{object} Using the Destination header, copies an existing object toanother object with a new name in the Cloud Files storagesystem.

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 mustbe in the format X-Object-Meta- name, where nameis 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 ServicesYou can perform the operations in the following table at the account level of your CloudFiles 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 authenticationtoken. You can check how to generate an authentication token in Section 3.1.2,“Retrieving the Authentication Token” [10]. Your authentication token and your accountinformation are in the service catalog that is produced.









28

5.1.1. List Account Containers




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 youraccount, 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 usingSQLite'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 containernames 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 getthe results in JSON or XML.

The HTTP response status code is a value from 200 to 299, inclusive. A 200 (OK) codereturns if there are containers, and a 204 (No Content) code returns if there are nocontainers.

Format Container List

If you append the ?format=xml or ?format=json query parameter to the storageaccount URL, the service returns container information serialized in the specified format. Toformat 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 containernames. You can control and limit this list of results by using the marker, end_marker, andlimit parameters. These parameters provide a mechanism to iterate through the entirelist of containers.

The marker parameter tells Cloud Files where to begin your list of containers andend_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,000containers. Note that the marker and end_marker values should be URL-encoded priorto sending the HTTP request.

You can use the limit parameter to reduce the number of returned objects.

http://www.sqlite.org/datatype3.html#collation

http://www.sqlite.org/datatype3.html#collation



29

If the number of returned items equals the limit used (or 10,000 if no limit wasspecified), 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 listand make another request with a marker of the last item returned:

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=bananas Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c kiwis oranges

Again, two items are returned, and you assume that there may be more. So you makeanother GET request for two more.

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=oranges Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c pears

This one-item response shows less than the limit of 2 container names requested, andindicates that this is the end of the list.

By using end_marker, you can limit the result set to container names less than the givenvalue.



30

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?end_marker=oranges Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c 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

(Optional)

For an integer value n, limits the number of results to n values.

marker String

(Optional)

Given a string value x, returns container names greater in value thanthe specified marker. Only strings using UTF-8 encoding are valid.

end_marker String

(Optional)

Given a string value x, returns container names less in value than thespecified marker. Only strings using UTF-8 encoding are valid.

format String

(Optional)

Value of the serialized response format - either json or xml.

Example 5.1. List Account Containers Request: XML

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=xml HTTP/1.1Host: storage.clouddrive.comContent-Length: 0X-Storage-Token: f064c46a782c444cb4ba4b6434288f7c}

Example 5.2. List Account Containers Request: JSON

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=json HTTP/1.1Host: storage.clouddrive.comContent-Length: 0X-Storage-Token: f064c46a782c444cb4ba4b6434288f7c}

5.1.1.2. Response

This table shows the Body parameters for the List Account Containers Response:


name String

(Required)

Name of the container.



31


count Int

(Required)

Number of objects in the container.

bytes Int

(Required)

Number of bytes in the container.

Example 5.3. List Account Containers Response: XML

HTTP/1.1 200 OKDate: Tue, 25 Nov 2008 19:42:35 GMTContent-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="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 OKDate: Tue, 25 Nov 2008 19:39:13 GMTContent-Type: application/json; charset=utf-8

[ {"name":"test_container_1", "count":2, "bytes":78}, {"name":"test_container_2", "count":1, "bytes":17}]



32

5.1.2. Create or Update Account Metadata



You can associate custom metadata headers with the account level URI. To create orupdate an account metadata header, submit a POST operation. These headers must havethe format X-Account-Meta-name. Replace name with name of your metadata. (Inthe 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 themetadata 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 MetadataRequest:


X-Account-Meta-name String

(Required)

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 yourmetadata.

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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Account-Meta-Book: MobyDickX-Account-Meta-Subject: Whaling

5.1.2.2. Response

Example 5.6. Create or Update Account Metadata Response

HTTP/1.1 204 No ContentContent-Length: 0



33

Content-Type: text/html; charset=UTF-8X-Trans-Id: tx1b4be419af2c4d688ee4d-0052cf1ea4dfw1Date: Thu, 09 Jan 2014 22:11:48 GMT



34

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. Inthe example, a 204 (No Content) code is returned. A 401 (Unauthorized) is returned for aninvalid 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

5.1.3.2. Response

This table shows the Header parameters for the Get Account Metadata Response:


X-Account-Object-Count Int

(Required)

The total number of objects that are stored in Cloud Files for theaccount.

X-Account-Bytes-Used Int

(Required)

The total number of bytes that are stored in Cloud Files for theaccount.

X-Account-Container-Count Int

(Required)

The total number of containers that are stored in the Cloud Files forthe account.

Example 5.8. Get Account Metadata Response

HTTP/1.1 204 No ContentContent-Length: 0



35

X-Account-Object-Count: 573X-Timestamp: 1369081921.78518X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284eX-Account-Bytes-Used: 14268918X-Account-Container-Count: 1Content-Type: text/plain; charset=utf-8Accept-Ranges: bytesX-Trans-Id: tx8e82a77399724e40a90e8-0052cf0e52dfw1Date: Thu, 09 Jan 2014 21:02:10 GMT



36

5.1.4. Delete Account Metadata



To delete a metadata header, use the POST operation to send an empty value for thatparticular header.

If the tool you use to communicate with Cloud Files does not support empty headers, suchas an older version of cURL, send the X-Remove-Account-Meta-name: arbitraryvalue 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-name

String

(Required)

Header to send to delete account metadata. Replace the name at theend of the header with the name for your metadata.

This table shows the URI parameters for the Delete Account Metadata Request:



Example 5.9. Delete Account Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Remove-Account-Meta-Book: x

5.1.4.2. Response

Example 5.10. Delete Account Metadata Response

HTTP/1.1 204 No ContentContent-Length: 0Content-Type: text/html; charset=UTF-8X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1Date: Thu, 09 Jan 2014 22:28:22 GMT

5.2. Container ServicesYou can perform the operations in the following table on containers in your Cloud Filesaccount.



37




• container, such as MyContainer

For your own requests, you must use your own account information, authenticationtoken, and container name. You can check how to generate an authentication token inSection 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token andyour account information are in the service catalog that is produced.











38

5.2.1. List Container Objects




This operation against a storage container name retrieves a list of objects stored in thecontainer. 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 thecontainer, up to 10,000 names. The response body shows the object names as one objectname per line. Specifying the query parameters filters the full list and returns a subset ofobjects. For information on limiting and controlling the list, see the following “Controlling aLarge 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 noobjects. If the container does not exist, or if an incorrect account is specified, a status code404 (Not Found) is returned.

For information on filtering the results of a container list, see Chapter 6, “PseudoHierarchical Folders and Directories” [66].

Format Object List

If you append the format=xml or the format=json query parameter to the storageaccount URL, the service returns additional object information serialized in the specifiedformat. The status codes are the same when using format=xml or format=json.However, Content-Type matches the specified format. The example responses below areformatted 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. Youcan limit and control this list of results by using the marker, end_marker, and limitparameters.

The marker parameter tells Cloud Files where to begin your list of objects, andend_marker tells where to end the list. You can use them either independently ortogether, separated by an ampersand (&). If you do not specify them, your list displays upto 10,000 objects. Note that the marker and end_marker values should be URL-encodedprior 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 wasspecified), you can assume there are more object names.

As an example, use a listing of 5 object names, as follows:

gala



39

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 Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c gala grannysmith

Because the request returned two items, assume there are more object names to list andmake another request with a marker of the last item returned:

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&marker=grannysmith Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c honeycrisp jonagold

Again, two items are returned, and you assume that there may be more. So you makeanother GET request for two more.

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&marker=jonagold Host: storage.clouddrive.com X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c reddelicious

This one-item response shows less than the limit of two object names requested, andindicates 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:



40


limit Int

(Optional)

For an integer n, limits the number of results to n values.

marker String

(Optional)

Given a string value x, returns object names greater in value than thespecified marker.

end_marker String

(Optional)

Given a string value x, returns object names less in value than thespecified marker.

prefix String

(Optional)

For a string value x, causes the results to be limited to object namesbeginning with the substring x.

format String

(Optional)

Specifies either json or xml to return the respective serialized response.

delimiter Char

(Optional)

For a character c, returns the object names nested in the container(without the need for the directory marker objects).

path String

(Optional)

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 '/' onthe end. For more information about pseudo paths, see the section onpseudo hierarchical folders and directories.

Example 5.11. List Container Objects Request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example 5.12. List Container Objects Request: XML

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=xml HTTP/1.1Host: storage.clouddrive.comX-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example 5.13. List Container Objects Request: JSON

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=json HTTP/1.1Host: storage.clouddrive.comContent-Length: 0X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

5.2.1.2. Response

This table shows the Header parameters for the List Container Objects Response:


Last-Modified String

(Required)

An internal variable that indicates the last time an entity (account,container, or object) was modified. Last-Modified has resolution up toone second. For Last-Modified, the time zone is UTC.

Example 5.14. List Container Objects Response

HTTP/1.1 200 OKDate: Thu, 07 Jun 2010 18:50:19 GMT



41

Content-Type: text/plain; charset=UTF-8Content-Length: 171kate_beckinsale.jpgHow To Win Friends And Influence People.pdfmoms_birthday.jpgpoodle_strut.movDisturbed - Down With The Sickness.mp3army_of_darkness.avithe_mad.avi

Example 5.15. List Container Objects Response: XML

HTTP/1.1 200 OKDate: Tue, 25 Nov 2008 19:42:35 GMTContent-Length: 643Content-Type: application/xml; charset=utf-8<?xml version="1.0" encoding="UTF-8"?><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 OKDate: Tue, 25 Nov 2008 19:39:13 GMTContent-Length: 387Content-Type: application/json; charset=utf-8[ {"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"}]



42

5.2.2. Create Container



This operation creates a Cloud Files container. Containers are storage compartments foryour data. The URL-encoded name must be less than 256 bytes and cannot contain aforward slash character (/). You can create up to 500,000 containers in your Cloud Filesaccount.

You can assign custom metadata for containers by including additional HTTP headers withan X-Container-Meta- prefix on the POST request. See Section 5.2.4, “Create or UpdateContainer Metadata” [45] for details on setting custom metadata.

Using custom container metadata, you can create information in the header to effectivelytag a container with metadata. The container metadata restrictions are the same as objectmetadata. You can have 4096 bytes maximum of overall metadata, with a maximum of90 distinct metadata items. Each can have a name length of up to 128 characters with amaximum of 256 bytes in the value. Any valid UTF-8 encoded string value is allowed formetadata. 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 forthe 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 thecontainer 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 themetadata 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

(Optional)

Custom container metadata. Replace the name at the end of theheader with the name for your metadata.

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.1Host: storage.clouddrive.com



43

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example 5.18. Create Container with Metadata Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Container-Meta-InspectedBy: JackWolf

5.2.2.2. Response

Example 5.19. Create Container Response

HTTP/1.1 201 CreatedDate: Thu, 07 Jun 2007 18:50:19 GMTContent-Type: text/plain; charset=UTF-8

Example 5.20. Create Container with Metadata Response

HTTP/1.1 201 CreatedDate: Thu, 07 Jun 2010 18:50:19 GMTContent-Type: text/plain; charset=UTF-8



44

5.2.3. Delete Container



A DELETE operation against a storage container permanently removes it. The containermust be empty before it can be deleted.

Before using DELETE, you can use a GET operation against the container to list any objectsit 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) isreturned if the requested container is not found. A status code of 409 (Conflict) is returnedif 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

5.2.3.2. Response

Example 5.22. Delete Container Response

HTTP/1.1 204 No ContentDate: Thu, 07 Jun 2007 18:57:07 GMTContent-Length: 0Content-Type: text/plain; charset=UTF-8



45

5.2.4. Create or Update Container Metadata



To set or edit container metadata, perform a POST operation to the container. Theoperation must include X-Container-Meta-name, where name is the name of yourcustom metadata. Subsequent POSTPOST to the header using the same metadata nameoverwrite the previous value.

To view your metadata changes, perform a HEAD operation on the container. (For moreinformation, see Section 5.2.5, “Get Container Metadata” [47].) Do not try to send themetadata in your HEAD request.

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) isreturned when the requested container does not exist.


Note

For information about adding metadata for the following purposes, seeChapter 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 MetadataRequest:



(Required)

The container metadata. Replace the name at the end of the headerwith the name of your metadata.

This table shows the URI parameters for the Create or Update Container MetadataRequest:




Example 5.23. Create or Update Container Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/



46

1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Container-Meta-Book: MobyDickX-Container-Meta-Subject: Whaling

5.2.4.2. Response

Example 5.24. Create or Update Container Metadata Response

HTTP/1.1 204 No ContentDate: Thu, 07 Mar 2012 20:42:51 GMTContent-Length: 0Content-Type: text/plain; charset=UTF-8



47

5.2.5. Get Container Metadata



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 ContainerMetadata” [45].

If the container exists, a status code of 2xx (between 200 and 299, inclusive) is returned. Ifthe 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

5.2.5.2. Response

This table shows the Header parameters for the Get Container Metadata Response:


X-Container-Object-Count Int

(Required)

The number of objects in the container.

X-Container-Bytes-Used Int

(Required)

The total number of bytes used for all objects in the container.


(Required)

Any metadata set on the container. The name at the end of theheader is the name of your metadata.



48


X-Timestamp String

(Required)

An internal variable that indicates the last time an entity (account,container, or object) was modified. The format is the same as a Unixtimestamp. The storage system uses this header to determine thelatest version. For example, during replication, the storage systemmakes sure all three object replicas are up to date, and it uses theX-Timestamp header to determine which replica is the latest. Youmay notice that objects have both a Last-Modified and X-Timestampheader. The difference between these two headers is the resolution.Last-Modified has resolution up to one second, while X-Timestamp hasresolution up to five decimal places of one second.

Example 5.26. Get Container Metadata Response

HTTP/1.1 204 No ContentDate: Thu, 08 Nov 2012 19:08:25 GMTContent-Type: text/html; charset=UTF-8X-Container-Object-Count: 5X-Container-Bytes-Used: 3846773X-Container-Meta-Book: MobyDickX-Container-Meta-Subject: Whaling



49

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 emptyheaders (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. arbitraryvalue 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 ContainerMetadata” [45].

A status code of 2xx (between 200 and 299, inclusive) indicates success. If the containerdoes 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-name

String

(Required)

The metadata to be deleted. Replace the name at the end of theheader with the name for your metadata.

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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Remove-Container-Meta-Subject: x

5.2.6.2. Response

Example 5.28. Delete Container Metadata Response

HTTP/1.1 204 No Content



50

Date: Thu, 09 Jan 2014 22:28:22 GMTContent-Length: 0Content-Type: text/html; charset=UTF-8X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1

5.3. Object ServicesYou can perform the operations in the following table on objects in your Cloud Filescontainers.





• 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 tokenin Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication tokenand your account information are in the service catalog that is produced.










51

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 therequest:

• 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 multipleranges, 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 thedata range, and LAST_BYTE_OFFSET to specify the end. You can omit theLAST_BYTE_OFFSET and if you do, the value defaults to the offset of the last byte ofdata.

• Suffix byte range specification: Use LENGTH bytes to specify the length of the datarange.

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 andthe 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 theresponse 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.

http://www.ietf.org/rfc/rfc2616.txt



52

Note

In the examples that follow that use ranges, the object contains the 10 bytes ofdata 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example 5.30. Get Object Data Request Using Range

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cRange: bytes=4-6

Example 5.31. Get Object Data Request Using Multiple Ranges

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cRange: bytes=1-3,2-5

5.3.1.2. Response

Example 5.32. Get Object Data Response

HTTP/1.1 200 OKDate: Wed, 14 Jul 2010 19:37:41 GMTLast-Modified: Mon, 12 Jun 2010 13:40:18 GMTETag: b0dffe8254d152d8fd28f3c5e0404a10Content-Type: text/htmlContent-Length: 512000

[ ...object content... ]

Example 5.33. Get Object Data Response Using Range

HTTP/1.1 206 Partial Content



53

Date: Wed, 14 Jul 2010 19:37:41 GMTLast-Modified: Mon, 12 Jun 2010 13:40:18 GMTETag: b0dffe8254d152d8fd28f3c5e0404a10Content-Type: application/octet-streamAccept-Ranges: bytesContent-Range: bytes 4-6/10Content-Length: 3

456

Example 5.34. Get Object Data Response Using Multiple Ranges

HTTP/1.1 206 Partial ContentDate: Wed, 14 Jul 2010 19:37:41 GMTLast-Modified: Mon, 12 Jun 2010 13:40:18 GMTETag: b0dffe8254d152d8fd28f3c5e0404a10Content-Type: multipart/byteranges;boundary=4789b20f24cc4d2a8da2e552e151e6feAccept-Ranges: bytesContent-Range: bytes 4-6/10Content-Length: 265

--4789b20f24cc4d2a8da2e552e151e6feContent-Type: application/octet-streamContent-Range: bytes 1-3/10

123--4789b20f24cc4d2a8da2e552e151e6feContent-Type: application/octet-streamContent-Range: bytes 2-5/10

2345--4789b20f24cc4d2a8da2e552e151e6fe--



54

5.3.2. Create or Update 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'sdata in the ETag header. You are not required to include the ETag header, but werecommend its use to ensure that the storage system successfully stores your object'scontent.

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, 1348691905represents Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific Epochtime, you indicate when you want the object to expire, not be served, and be deletedcompletely from the storage system. When Cloud Files detects one of these headers, thesystem automatically stops serving that object at the specified date and time, and shortlyafter 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 withyour content's MD5 locally to perform the end-to-end data validation on the client side. Formanifest objects, the ETag is the MD5 checksum of the concatenated string of ETags foreach 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 achecksum and to see if you get a 404 (Not Found) status code when you do aGET, HEAD, POST, or DELETE.

Objects can be assigned custom metadata by including additional HTTP headers in the PUTrequest. 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 specifyContent-Type: audio/mpeg3 for mp3 files.

A status code of 201 (Created) indicates a successful write. Any status code in the 400range denotes failure. The 401 (Unauthorized) status code is returned upon authenticationfailure. The 411 (Length Required) status code denotes a missing Content-Length orContent-Type header in the request. If the MD5 checksum of the data written to thestorage system does NOT match the optionally supplied ETag value, a 422 (UnprocessableEntity) status code is returned.

No response body is returned.



55


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

(Optional)

The MD5 checksum of your object's data.

Content-Type String

(Optional)

The media type of the entity-body sent. If not specified, theContent-Type is guessed, by using the Python mimetypes library,based on the object path.

Content-Disposition String

(Optional)

The new browser behavior for the file, so that the downloader cansave the file rather than displaying it using default browser settings.

Content-Encoding String

(Optional)

The underlying media type of the compressed file.

X-Delete-At Int

(Optional)

The certain date, in the format of a Unix Epoch timestamp, when theobject will be removed.

X-Delete-After Int

(Optional)

The certain date, in the format of a Unix Epoch timestamp, after whichthe object will be removed.

X-Object-Meta-name String

(Optional)

The custom object metadata. name at the end of this headerrepresents the name of your metadata.

X-Detect-Content-Type String

(Optional)

If you set this header to True, the Content-Type that is sent in therequest (if any) is ignored, and Content-Type is guessed by usingthe 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cETag: 8a964ee2a5e88be344f36c22562a6486Content-Length: 512000X-Delete-At: 1339429105Content-Disposition: attachment; filename=platmap.mp4Content-Type: video/mp4Content-Encoding: gzipX-Object-Meta-PIN: 1234

[ ...object content... ]



56

5.3.2.2. Response

Example 5.36. Create or Update Object Response

HTTP/1.1 201 CreatedDate: Thu, 07 Jun 2010 18:57:07 GMTETag: d9f5eb4bba4e2f2f046e54611bc8196bContent-Length: 0Content-Type: text/plain; charset=UTF-8



57

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 subsequentGET, HEAD, POST, or DELETE operations return a 404 (Not Found) error unless objectversioning is on and other versions exist. For more information about object versioning, seeSection 8.6, “Object Versioning” [79].

Objects with the X-Delete-At or X-Delete-After header assigned are deletedwithin one day of the expiration time, and the object is not served immediately afterthe expiration time. For more details, refer to Section 8.5, “Expiring Objects with the X-Delete-After and X-Delete-At Headers” [78].

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) isreturned 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

5.3.3.2. Response

Example 5.38. Delete Object Response

HTTP/1.1 204 No Content



58

Date: Thu, 10 Jun 2010 20:59:39 GMTContent-Type: text/plain; charset=UTF-8



59

5.3.4. Copy Object




PUT v1/{account}/{container}/{object} Using the X-Copy-From header, copies an existing object toanother object with a new name in the Cloud Files storagesystem bu us.

Suppose you upload a file with the wrong object name or content type, or you need tomove some objects to another container. Without a server-side object copy feature, youwould 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 contentand 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 theX-Copy-From header to designate the source of the data. The header value should be thecontainer and object name of the source object in the form of /container/object. TheHTTP 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 performthe 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 informationabout how to handle objects larger than 5 GB, see Section 8.2, “Create LargeObjects” [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 existingobject, and include the Destination header to specify the destination of the copy. Theheader 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



60

With both of these methods, the destination container must exist before attempting thecopy.

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 byissuing several concurrent COPY commands. Because Cloud Files is a distributedstorage system, your concurrent COPY commands run on separate machinessimultaneously, which is much better than waiting for one copy to finish beforestarting the next COPY command. As a rule of thumb, you can run up to 100concurrent COPY commands per container (running more will have diminishingimprovement).

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 sourceobject after copying it. A move is simply a COPY followed by a DELETE. All metadata ispreserved during the object copy. Note that you can set metadata on the request to copythe object (with either the PUT or the COPY) and the metadata overwrites any conflictingkeys on the destination object.

Your account is not charged when you copy or move your objects within the same datacenter using the internal network URI, ServiceNet, as the storage URL. You can find yourServiceNet endpoint in the service catalog created when you authenticate your session. Forinformation 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 asinternalURL. The name is your Cloud Files storage URL with snet- pre-pended to it. Ifyou do not know which data center you are working in, you can find it in the Cloud ControlPanel. (For more information about service access endpoints, see Section 3.3, “ServiceAccess 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"



61

} ]


5.3.4.1. Request

This table shows the Header parameters for the Copy Object Request:


X-Copy_From String

(Optional)

Used with PUT, the container and object name of the source object inthe form of /container/object.

Content-Length Int

(Required)

Used with PUT, the content length. Zero (0) is always acceptable herefor this operation.

Destination String

(Optional)

Used with COPY, the container and object name of the destinationobject in the form of /container/object.

Content-Type String

(Optional)



(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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Copy-From: /MySourceContainer/MySourceObjectContent-Length: 0

Example 5.43. Copy Object Request Using COPY

COPY /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MySourceContainer/MySourceObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cDestination: /MyDestinationContainer/MyDestinationObject

5.3.4.2. Response

This operation does not return a response body.



62

5.3.5. Get Object Metadata



HEAD operations on an object are used to retrieve object metadata and other standardHTTP headers.

The only required header to be sent in the request is X-Auth-Token for the authorizationtoken.

A status code of 200 (OK) indicates success. Status code 404 (Not Found) is returned whenthe 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 2xxstatus code denotes success. When a HEAD request is performed againstthe container, it queries the container databases, and it does not retrievethe content from them. Thus, this returns the 204 (No Content) status code.However, when a HEAD request is performed against the object, it returns a200 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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

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



63


(Required) timestamp. The storage system uses this header to determine thelatest version. For example, during replication, the storage systemmakes sure all three object replicas are up to date, and it uses theX-Timestamp header to determine which replica is the latest. Youmay notice that objects have both a Last-Modified and X-Timestampheader. The difference between these two headers is the resolution.Last-Modified has resolution up to one second, while X-Timestamp hasresolution up to five decimal places of one second.

Last-Modified String

(Required)

An internal variable that indicates the last time an entity (account,container, or object) was modified. For Last-Modified, the time zoneis UTC. You may notice that objects have both a Last-Modified and X-Timestamp header. The difference between these two headers is theresolution. 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 OKDate: Thu, 10 Jun 2010 20:59:39 GMTLast-Modified: Fri, 11 Jun 2010 13:40:18 GMTETag: 8a964ee2a5e88be344f36c22562a6486Content-Length: 512000Content-Type: text/plain; charset=UTF-8X-Object-Meta-Meat: BaconX-Object-Meta-Fruit: AppleX-Object-Meta-Veggie: BeansX-Object-Meta-Dairy: Cheese



64

5.3.6. Update Object Metadata



You can set or update your custom metadata for existing objects by using a POST requestto the object name.

Metadata is set by using the header X-Object-Meta-name: Foo where name isthe 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 namewith 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 therequest. Otherwise, the metadata is not removed.

For information on working with metadata when copying objects, see Section 5.3.4, “CopyObject” [59].

Deleting Object Metadata

All the object metadata is set at the same time. If you want to edit or removeone header, simply POST all other headers leaving out the header that youwant to remove. This means that if you delete one entry without posting theothers, the others will also be deleted at that time.

To remove all metadata on an object, simply perform a POST request for theobject 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 returnedif 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

(Optional)

The container metadata. name represents the name of yourmetadata.



65


X-Delete-At Int

(Optional)

The date, in the format of a Unix Epoch timestamp, when the objectwill be removed.

X-Delete-After Int

(Optional)

The date, in the format of a Unix Epoch timestamp, after which theobject is removed.

Content-Type String

(Optional)



(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.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Object-Meta-Fruit: AppleX-Object-Meta-Veggie: Carrot

5.3.6.2. Response

Example 5.47. Update Object Metadata Response

HTTP/1.1 202 AcceptedDate: Thu, 07 Jun 2007 20:59:39 GMTContent-Length: 0Content-Type: text/plain; charset=UTF-8



66

6. Pseudo Hierarchical Folders andDirectories

Although you cannot nest directories in Cloud Files, you can simulate a hierarchicalstructure within a single container by adding forward slash characters (/) in the objectname. To navigate the pseudo directory structure, you can use the delimiter queryparameter. For an illustration, see the examples below.

Note

In the example below, the objects reside in a container called backups. Withinthat container, the objects are organized in a pseudo directory called photos.Keep in mind that the container name is not displayed in the example, butthat it is a part of the object URIs. For instance, the URI of the picture me.jpgis 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 delimiteror 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.jpgphotos/animals/cats/siamese.jpgphotos/animals/dogs/corgi.jpgphotos/animals/dogs/poodle.jpgphotos/animals/dogs/terrier.jpgphotos/me.jpgphotos/plants/fern.jpgphotos/plants/rose.jpg

Use the delimiter parameter to limit the displayed results. Any character may be used as adelimiter. 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. Becausethe request used the slash, only the pseudo directory photos/ displays. Keep in mindthat the returned values from a slash delimiter query are not real objects. They have aContent-Type of application/directory and are in a subdir section of JSON andXML results.

photos/

Use the prefix parameter with the delimiter parameter to view the objects inside apseudo 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 thetop level pseudo directory.



67

photos/animals/ photos/plants/photos/me.jpg

There is no limit to the amount of nested pseudo directories you can create. In order tonavigate through them, use a longer prefix parameter coupled with the delimiterparameter. In the sample output below, there is a pseudo directory called dogs within thepseudo 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 thenested pseudo directory.

photos/animals/dogs/corgi.jpgphotos/animals/dogs/poodle.jpgphotos/animals/dogs/terrier.jpg



68

7. Additional Container ServicesInformation

The following section describes additional metadata options for containers in Cloud Files.

7.1. Container QuotasThe container_quotas middleware implements simple quotas that can be imposed on CloudFiles containers by a user (most likely the account administrator) with the access to setcontainer 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 entitytoo large) with a descriptive body.

Because the storage system is a true distributed system and because it accepts simultaneousrequests, the quotas may not be enforced exactly. For example, if the quota is 5 GB andtwo users try to store a 5 GB file at the exact same time, both would be allowed to storethe 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 willeventually exceed the quota because the storage system does not know whether the endof the file will exceed the quota.

Quotas are set by adding metadata to the container. The available metadata values aredescribed 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 DeliveryYou can use Access Log Delivery to analyze the number of requests for each object, theclient 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. Toenable 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, youmust 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 everycontainer for which you turn on logging. Log files exist until you delete them. To turn offlogging, set X-Container-Meta-Access-Log-Delivery flag to FALSE.

Log files are named according to this pattern: containername, log date, log hour, and MD5_hash such asMedia/2012/10/01/16/096e6c4473f235db081deb51f42a8d98.log.gz . In this



69

example, Media is the name of the container, October 1, 2012 is the date, and 16 is thehour the logs are from. There may be multiple files for a given hour because the storagesystem splits log files based on both time and log file size. All times in the access logs areUTC time.

Within the gzipped logs, the format of the entries is similar to National Center forSupercomputing Applications (NCSA) combined log format, but without cookies. Thepattern is below. The dashes ("-") note fields which the NCSA combined log formatdictates 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/ MossoCloudFS_bb88c7b9-ea5b-49af-82fc-376ff241963c/CharacterTest_%2521 /object_%2521 HTTP/1.0" 201 118 "-" "python-requests/0.13.8 CPython/2.7.3 Linux/3.2.0-29-generic" 50.56.228.64 - - [27/08/2012:16:53:47 +0000] "PUT /v1/ MossoCloudFS_bb88c7b9-ea5b-49af-82fc-376ff241963c/CharacterTest_%2521 HTTP/1.0" 202 58 "-" "python-requests/0.13.8 CPython/2.7.3 Linux/3.2.0-29-generic" 50.56.228.64 - - [27/08/2012:16:50:36 +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"



70

8. Additional Object Services InformationThe following sections provide additional information about using objects in Cloud Files.

8.1. Chunked Transfer EncodingYou can upload data without needing to know in advance the amount of data to beuploaded. 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 beperforming a DB dump, piping the output to gzip, and then piping the gzip file directly toCloud Files without having to write the data to disk to compute the file size. If you attemptto upload more than 5 GB, the server will close the connection and remove the previouslysent data from the system. You must ensure that the data that you transfer will be lessthan 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 segmentthem prior to upload, upload them to the same container, and then use a manifest file toallow downloading of a concatenated object containing all the segmented objects. Formore information, see Section 8.2.1, “Dynamic Large Object Creation” [72].

Example 8.1. Upload Unspecified Quantity of Content Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cTransfer-Encoding: chunkedX-Object-Meta-PIN: 1234

Example 8.2. Upload Unspecified Quantity of Content Response

19A bunch of data broken upDinto chunks.0

8.2. Create Large ObjectsThe content of an object cannot be larger than 5 GB (by default). However, you can storelarger content by using two types of objects:

• Segment objects: You divide your content into pieces and upload each piece into its ownobject, 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, thesystem concatenates the contents of the segment objects and returns this in the responsebody of the request. This behavior extends to the response headers returned by GET andHEAD operations. The Content-Length is the total size of all segment objects and



71

the ETag is calculated by taking the ETag value of each segment, concatenating themtogether, and then returning the MD5 checksum of the result.

Note

If you use the COPY operation using a manifest object as the source, the newobject is a "normal" object (not segmented). If the total size of the sourcesegment objects exceeds 5GB, the COPY operation will fail. However, you canmake a duplicate of the manifest object. This new object can be larger than5GB.

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 isthe name of the container where the segment objects are stored and prefix is a stringthat all the segment objects have in common.

• Static Large Objects: The manifest object content is an ordered list of the names of thesegment objects in JSON format.

While both types of manifest objects have similar behavior, there are differences asexplained in the following table.



72

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 includesthe MD5 checksum (ETag) of eachsegment. You cannot upload themanifest object if the ETag in thelist differs from the segment objectalready uploaded. If a segmentis somehow lost, an attempt todownload the manifest object willresult in an error.

Not guaranteed. The eventualconsistency model means thatalthough you may have uploaded asegment object, it may not appearin the container listing until later. Ifyou download the manifest before itappears in the container, it will notform part of the content returned inresponse to a GET request.

Upload order The segment objects must be uploadedbefore the manifest object.

You can upload manifest andsegment objects in any order. Werecommend that you upload themanifest object after the segmentsin case a premature download of themanifest occurs. However, this is notenforced.

Removal or addition of segmentobjects

You cannot add or remove segmentobjects from the manifest. However,you can create a completely newmanifest object of the same name witha different manifest list.

You can upload new segment objectsor remove existing segments –the names must simply match the<prefix> supplied in X-Object-Manifest.

Segment object size and number Segment objects must be at least 1MBin size (by default). The final segmentobject can be any size. At most 1000segments are supported (by default)

Segment objects can be of any size.

Segment object container name The manifest list includes the containername of each object, i.e., segmentobjects may be in different containers.

All segment objects must be in thesame container.

Manifest object metadata The object has X-Static-Large-Object set to True. You do not setthis metadata directly. Instead thesystem sets it when you PUT a staticmanifest object.

The X-Object-Manifest value isthe container/prefix indicatingwhere the segment objects arelocated. You supply this requestheader in the PUT operation

Making a copy of the manifest object To make a copy of the manifestobject, include the ?multipart-manifest=get query string withthe COPY operation. The new objectcontains the same manifest as theoriginal. The segment objects are notcopied. Instead, both the original andnew manifest objects share the sameset of segment objects.

The COPY operation does not createa manifest object. To duplicatea manifest object, use the GEToperation to read the value of X-Object-Manifest and use thisvalue in the X-Object-Manifestrequest header in a PUT operation.This creates a new manifest objectthat shares the same set of segmentobjects as the original manifestobject.

8.2.1. Dynamic Large Object Creation

Objects that are larger than 5 GB must be segmented, prior to upload. You then uploadthe segments as you would any other object. You create a manifest object telling CloudFiles how to find the segments of the large object. The segments remain individuallyaddressable, 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.



73

Note

The eventual consistency model means that although you may have uploadeda segment object, it may not appear in the container listing until later. If youdownload the manifest before it appears in the container, it will not form partof the content returned in response to a GET request.

To ensure that the download works correctly, you must upload all the object segmentsto the same container and that ensure each object name is prefixed in such a way thattheir names sort in the order in which they should be concatenated. You also create andupload 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 thatthe object segments are in and prefix is the common prefix for all the segments. Thecontainer 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 thismethod, 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 themanifest to point to this new location. During the upload of the new segments, the originalmanifest 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 bymistake, a Dynamic Large Object, having no way of knowing the segment wasever there, ignores the deleted file, and the user is returned an incomplete file.

Example 8.3. Upload Segment of a Large Object Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cETag: 8a964ee2a5e88be344f36c22562a6486Content-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 optionallysupplied ETag value, a 422 (Unprocessable Entity) status code is returned.

You can continue uploading segments as this example shows, prior to uploading themanifest.



74

Example 8.5. Upload Next Segment of the Large Object Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cETag: 8a964ee2a5e88be344f36c22562a6486Content-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 objectsegments reside. Note that uploading additional segments after the manifest is created willcause the concatenated object to be that much larger but you do not need to recreate themanifest file for subsequent additional segments.

Example 8.7. Upload Manifest Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cContent-Length: 0X-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 themanifest.

Note

The ETag in the response for a GET or HEAD on the manifest file is the MD5sum of the concatenated string of ETags for each of the segments in themanifest. Usually, the ETag is the MD5 sum of the contents of the object, andthat holds true for each segment independently. But it is not meaningful togenerate such an ETag for the manifest itself, so this method was chosen to atleast offer change detection.

The response's Content-Type for a GET or HEAD request on the manifest will be thesame as the Content-Type set during the PUT request that created the manifest. You caneasily 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 becauseit allows you to upload many objects concurrently and afterwards downloads them as asingle object. However, unlike Dynamic Large Object support, Static Large Object supportdoes not rely on eventual consistency model for the container listings. Instead, Static LargeObject support uses a user-defined manifest of the object segments.



75

The benefits of using Static Large Objects are:

• Uploads and downloads of Static Large Objects can be in different containers, which canimprove 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 eachpiece. You must record the ETag response header returned by the PUT operation.Alternatively, you can calculate the MD5 checksum of the segment prior to uploadingand include this in the ETag request header – this ensures that the upload cannotcorrupt your data.

The maximum number of object segments per Static Large Object is 1,000. Eachsegment, 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 includingthe ?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 lastone, need to be larger than 1 megabyte (1048576 bytes). It may help organizationallyto keep them in the same container, but it is not required. You will need the followinginformation 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 youuploaded 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 manifestobject name:

?multipart-manifest=put

The body of the PUT operation is an ordered list of files in JSON data format. The data tobe 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 youuploaded the segment. This is the MD5 checksum of the segment object's data.



76

• 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 thatin contrast to dynamic large objects, you can use a number of containers and the objectnames 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. Asimilar situation applies to the ETag . If used in the PUT operation, it must contain theMD5 checksum of the JSON content. The ETag metadata value is then set to be the MD5checksum of the concatenated ETag values of the object segments. You can also set theContent-Type request header and custom object metadata.

When the PUT operation sees the ?multipart-manifest=put query string, it readsthe request body and verifies that each segment object exists and that the sizes and ETagsmatch. If there is a mismatch, the PUT operation will fail.

On upload, the middleware will head every segment passed in and verify the size andETag of each. If any of the objects do not match (not found, size/ETag mismatch, belowminimum size), Cloud Files issues a 4xx status code. If everything does match, Cloud Filesissues a 2xx status code.

If everything matches, the manifest object is created. The X-Static-Large-Objectmetadata 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 segmentin the manifest exists and that it matches the specifications. However, nothing prevents auser from breaking the Static Large Object download by deleting or replacing a segmentreferenced 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 thesegments will be concatenated on download. The manifest can reference objects inseparate containers, which improves concurrent upload speed. Objects can be referencedby multiple manifests.



77

8.2.2.3. Retrieving a Large Object

A GET request to the manifest object returns the concatenated content of the segmentobjects listed in the manifest. If any of the segments from the manifest are not found ortheir ETag or Content-Length no longer match, the GET operation will fail and you willreceive 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 asshown below:

• Content-Length: The total size of the Static Large Object (the sum of the sizes of thesegments in the manifest)

• X-Static-Large-Object: True

• ETag: The ETag of the Static Large Object (generated the same way as Dynamic LargeObject)

The GET request with the following query parameter returns the actual manifest filecontents:

?multipart-manifest=get

The response body contains generated JSON. The resulting list will not be identicallyformatted 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 segmentobjects are not affected.

A DELETE operation with the following query parameter deletes all segment objectsin the manifest, and then, if all are successfully deleted, the manifest object itself. Afailure response will be similar to those for the bulk delete operation (Section 12.3, “BulkDelete” [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 totalsize of the concatenated segments in the manifest, not the size of the manifest file itself.



78

The overall X-Container-Bytes-Used for the container (and for the account) does notreflect the total size of the manifest, but the actual size of the stored JSON data. This allowsyou to see the total size of the Static Large Object in a container listing, but does not inflatethe 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 theidentity 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 anyautomatic compression. The Content-Encoding header enables the client to set themetadata appropriately.

In the following example, the Content-Encoding header indicates the type of encodingused on the data.

Example 8.10. Request with Content-Encoding

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cContent-Type: video/mp4Content-Encoding: gzip

8.4. Enabling Browser Bypass with the Content-Disposition Header

When an object is assigned the Content-Disposition header, you can override abrowser's default behavior for a file so that the browser prompts to save the file ratherthan displaying it using default browser settings.

In the following example, the Content-Disposition header is assigned with anattachment type that indicates how the file should be downloaded.

Example 8.11. Request with Content-Disposition

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cContent-Type: image/tiffContent-Disposition: attachment; filename=platmap.tif

8.5. Expiring Objects with the X-Delete-Afterand X-Delete-At Headers

When an object is assigned either an X-Delete-After or X-Delete-At header whenperforming a PUT or POST on the object, it is scheduled for deletion. This feature is helpful



79

for objects that you do not want to permanently store, such as log files, recurring fullbackups of a dataset, or documents or images that you know will be outdated at a futuretime.

Objects with the X-Delete-At or X-Delete-After header assigned are deletedwithin one day of the expiration time, and the object is not served immediately after theexpiration 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 specificEpoch time, you indicate when you want the object to expire, not be served, and bedeleted completely from the storage system.

The X-Delete-After header takes an integer number of seconds that represents theamount of time from now that you want the object to be deleted. The proxy server thatreceives the request converts this header into an X-Delete-At header and calculates thedeletion 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 UnixEpoch 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

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cContent-Type: image/jpegX-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

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cContent-Type: image/jpegX-Delete-After: 864000

8.6. Object VersioningObject versioning allows you to store multiple versions of your content to recover fromunintended overwrites and deletions. It provides an easy method to implement versioncontrol which can be used on any type of content. Rackspace strongly recommends thatyou 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-currentversion to be written to the separate container. Each of the non-current versions has atimestamp appended to it, so you know when it was originally created.

http://www.epochconverter.com/

http://www.epochconverter.com/



80

To enable object versioning, create a container where your non-current versions will bewritten. Next, set the metadata X-Versions-Location header on the container thatholds the current versions of your objects. Set the metadata header to point to the newnon-current version container that you created. This is where your non-current versions willbe stored. Once this is done, each object in your current-version container will have objectversioning enabled. Changes to the objects automatically create non-current versions in theseparate container.

Nothing is written to the non-current version container when you initially PUT an objectinto the current-version container. Only when you make edits to the objects with a PUTrequest will you create non-current versions. These non-current versions are labeledaccording 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 characterlength of the {objectName} and {timestamp} from when it was originally created as acurrent version.

Any return status in the 2xx range, such as 202 (Accepted), denotes success. Status codesin the 4xx or 5xx range denote failure. You should retry your request if you receive anerror. 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 theversioned 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 doany request redirects or metadata lookups.

A POST to a versioned object only updates the object's metadata. It does not create a newversion of the object. In other words, new versions are only created when the content ofthe object changes.

A DELETE to a versioned object removes the current version of the object and replaces itwith the next-most current version, moving it from the non-current container to the currentcontainer. This next-most current version carries with it any metadata last set on it. If wantto completely remove an object and you have five total versions of it, you must DELETE itfive times.

Note

A large-object manifest file cannot be versioned, but it can point to versionedsegments.

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 namesit versions. Then create a container with the X-Versions-Location header. Inthis 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 isversions. The location for the current version is the container current.



81

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 thatreferences 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 numberfor 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/



82

9. API Operations for CDN ServicesThis chapter provides further description for several of the API operations described inChapter 5, “API Operations for Storage Services” [26]. These API operations have a specificpurpose 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 thecloudFilesCDN section of the service catalog that you obtain during successfulauthentication. (For more information, see Section 3.1, “Authentication” [10] andSection 3.3, “Service Access Endpoints” [20].)

A CDN-enabled container is a public container that is served by Akamai's ContentDistribution Network. The files in a CDN-enabled container are publicly accessible and donot require an authentication token for read access. However, uploading content into aCDN-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 publiclyaccessible.)

The following sections describe the operations that you can perform within the storagesystem:

• Chapter 9, “API Operations for CDN Services” [82] describes operations that you canperform at the account level for Cloud Files CDN services.

• Section 9.2, “CDN Container Services” [84] describes operations that you can performon containers.

• Section 9.3, “CDN Object Services” [93] describes operations that you can perform onobjects.

9.1. CDN Account ServicesYou can perform the operation in the following table at the account level of your CloudFiles CDN account.




For your own requests, you must use your own account information and authenticationtoken. You can check how to generate an authentication token in Section 3.1.2,“Retrieving the Authentication Token” [10]. Your authentication token and your accountinformation are in the service catalog that is produced.


GET v1/{account}{?enabled_only,limit,marker,end_marker,format}

Lists CDN-enabled containers sorted by name.



83

9.1.1. List CDN-Enabled Containers


GET v1/{account}{?enabled_only,limit,marker,end_marker,format}

Lists CDN-enabled containers sorted by name.

GET operations against the cloudFilesCDN endpoints for an account retrieve a listof CDN-enabled containers. (For the CDN endpoints, see Section 3.3, “Service AccessEndpoints” [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 supportto return only the list of containers that are CDN-enabled.

The list of CDN-enabled containers is returned in the response body, one container nameper 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) codereturns if there are containers, and a 204 (No Content) code returns if there are nocontainers.

To view the CDN container details, see Section 9.2.2, “List a CDN-Enabled Container'sMetadata” [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

(Optional)

Set to true to return only CDN-enabled containers.

limit Int

(Optional)

For an integer value n, limits the number of results to n values.

marker String

(Optional)

Given a string value x, returns container names greater in value thanthe specified marker. Only strings using UTF-8 encoding are valid.Using marker provides a mechanism to iterate through the entire listof containers.

end_marker String

(Optional)

Given a string value x, returns container names less in value than thespecified end marker. Only strings using UTF-8 encoding are valid.

format String

(Optional)

Value of the serialized response format - either json or xml.



84

Example 9.1. CDN-Enabled Containers List Request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?enabled_only=true HTTP/1.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

9.1.1.2. Response

Example 9.2. CDN-Enabled Containers List Response

HTTP/1.1 200 OKDate: Thu, 08 Sep 2011 14:35:45 GMTTransfer-Encoding: chunkedContent-Type: text/plain imagesmovies

9.2. CDN Container ServicesYou can perform the operations in the following table on CDN-enbled containers in yourCloud 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 storageservice become CDN-enabled. After you CDN-enable a container, its publicly-available URIcan 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 objectbefore it is added to the container.

When you enable a container in the CDN service, you automatically generate URIs forSSL 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 enhancethe security of the Content Delivery Network. Any URIs set in the olderformat (http://c25810.r10.cf1.rackcdn.com/mydog.jpg) continueto 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, notonly can anyone view it, but anyone can link to it. We recommend that youmonitor your bandwidth usage and charges in the Cloud Control Panel. Thisway, you know if someone is hot linking your content. For helpful instructionsfor keeping yourself informed about your usage charges, see the KnowledgeCenter article "Protect your Cloud Files CDN Bill from Unexpected Usage".



http://www.rackspace.com/knowledge_center/article/protect-your-cloud-files-cdn-bill-from-unexpected-usage-0



85



For your own requests, you must use your own account information, authenticationtoken, and container name. You can check how to generate an authentication token inSection 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication token andyour 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.



86

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-enablethe container, perform a PUT request against it using the publicURL noted in the servicecatalog for Cloud Files during Authentication and set the X-CDN-Enabled header toTrue.

Section 3.1.2, “Retrieving the Authentication Token” [10] provides an example of theinformation in the service catalog for cloudfilesCDN.

When a container is CDN-enabled, any objects stored in it are publicly accessible over thecontent 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 endpointfor operations against the CDN management service, but you should usewhatever your authentication request provides. For more information aboutyour authentication request, see Section 3.1, “Authentication” [10]. For moreinformation about service access endpoints, see Section 3.3, “Service AccessEndpoints” [20].

Any CDN-accessed objects are cached in the CDN for a specified amount of time called theTime To Live (TTL). Each time the object is accessed after the TTL expires, the CDN refetchesand 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 andCache-Control headers for the cached object. The minimum TTL is 15 minutes (900seconds), 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 stayspopulated on CDN edge servers for the entire period. The most popular objects stay cachedbased on the edge location's logic.

Note

On August 13, 2012, the maximum TTL was set to 31536000 (one year). If youset 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, itwill 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, andthe TTL is adjusted. A status code of 204 (No Content) indicates the container was CDN-enabled as requested, but has no content.




87

In order to remove the container from the CDN, change the X-Cdn-Enabled headerto False, as in the request below. However, note that objects remain on the CDN edgeserver and are served to the public until their TTL expires.

Note

The CDN URI is unique per container. After the container is CDN-enabled, youcan make a HEAD request to the Cloud Files CDN endpoint with the containername to return the CDN URI in the X-Cdn-Uri header. You can use a cURLrequest 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 ContainerRequest:


X-Ttl Int

(Optional)

Specifies the Time To Live in seconds for an object to be cached in theCDN. The default value is 259200 seconds, or 72 hours.

X-Cdn-Enabled String

(Optional)

Indicates if a container is CDN-enabled. Valid values are True and False.

This table shows the URI parameters for the CDN-Enable and CDN-Disable a ContainerRequest:




Example 9.3. CDN-Enable Container Request

UT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c X-Ttl: 259200X-Cdn-Enabled: True

Example 9.4. CDN-Disable Container Request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c X-CDN-Enabled: False

9.2.1.2. Response

This table shows the Header parameters for the CDN-Enable and CDN-Disable a ContainerResponse:



88


X-Cdn-Uri Int

(Optional)

Indicates the URI that you can combine with object names to serveobjects through the CDN.

Example 9.5. CDN-Enable Container Response

HTTP/1.1 204 No ContentX-Cdn-Ssl-Uri: https:// 83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.comX-Ttl: 259200X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.cf0.rackcdn.comX-Cdn-Enabled: TrueX-Log-Retention: FalseX-Cdn-Streaming-Uri: http:// 084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.rackcdn. comX-Trans-Id: tx82a6752e00424edb9c46fa2573132e2cContent-Length: 0



89

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 acontainer where the Host header value is one of the cdnCloudFiles service accessendpoints. (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 inthe response for plain text, or in the response body for XML or JSON, if you request eitheras 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 yourprivate 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 MetadataRequest:




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


format String

(Optional)

The optional format the returned information. Either XML or JSON.

Example 9.6. List a CDN-Enabled Container's Metadata Request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example 9.7. List a CDN-Enabled Container's Metadata Request: JSON

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=json



90

Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example 9.8. List a CDN-Enabled Container's Metadata Request: XML

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=xmlHost: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

9.2.2.2. Response

This table shows the Header parameters for the List a CDN-Enabled Container's MetadataResponse:


X-Cdn-Uri String

(Required)

The URI for downloading the object over HTTP. This URI can becombined with any object name within the container to form thepublicly accessible URI for that object for distribution over a CDNsystem.

X-Ttl Int

(Required)

The TTL value in seconds. The minimum TTL is 15 minutes (or 900seconds), and the maximum is 50 years (1577836800 seconds).

X-Cdn-Enabled Boolean

(Required)

True or False to indicate whether the container is currently marked toallow public serving of objects through CDN

X-Log-Retention Boolean

(Required)

True or False to indicate whether the CDN access logs should becollected and stored in the Cloud Files storage system.

X-Cdn-Ssl-Uri String

(Required)

The URI for downloading the object over HTTPS, using SSL. (The usercannot have custom SSL certificates because our CDN partner does notprovide that feature.

X-Cdn-Streaming-Uri String

(Required)

The URI for video streaming that uses Adobe’s HTTP DynamicStreaming.

X-Cdn-Ios-Uri String

(Required)

The URI for video streaming that uses Apple’s HTTP Live Streaming.

Example 9.9. Get CDN-Enabled Container Metadata Request

HTTP/1.1 204 No ContentX-Cdn-Ssl-Uri: https:// 83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.comX-Ttl: 259200X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.cf0.rackcdn.comX-Cdn-Enabled: TrueX-Log-Retention: FalseX-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d 659bfc1ac1.r49.stream.cf0.rackcdn.comX-Trans-Id: tx82a6752e00424edb9c46fa2573132e2cContent-Length: 0

Example 9.10. List a CDN-Enabled Container's Metadata Response: JSON

HTTP/1.1 200 OK



91

Date: Tue, 30 Oct 2012 17:57:28 GMTContent-Length: 267Content-Type: application/xml; charset=utf-8<?xml version="1.0" encoding="UTF-8"?><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 OKDate: Tue, 30 Oct 2012 14:41:29 GMTContent-Length: 127Content-Type: application/json; charset=utf-8[ {"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"} ]



92

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

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) isreturned if the requested container is not found.




9.2.3.1. Request

This table shows the Header parameters for the Update CDN-Enabled Container MetadataRequest:


X-Log-Retention Boolean

(Optional)

True or False to indicate whether the CDN access logs should becollected and stored in the Cloud Files storage system.

X-Cdn-Enabled Boolean

(Optional)

True or False to enable or disable public sharing over the CDN. Keepin mind that if you have content currently cached in the CDN, settingyour container back to private will NOT purge the CDN cache. Youhave to wait for the TTL to expire or purge the objects.

X-Ttl Int

(Optional)

The TTL value in seconds. The minimum TTL is 15 minutes (or 900seconds), and the maximum is 50 years (1577836800 seconds).

This table shows the URI parameters for the Update CDN-Enabled Container MetadataRequest:




Example 9.12. Update CDN-Enabled Container Metadata Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Ttl: 86400X-Cdn-Enabled: TrueX-Log-Retention: True



93

9.2.3.2. Response

Example 9.13. Update CDN-Enabled Container Metadata Response

HTTP/1.1 204 No ContentX-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.ssl.cf0.rackcdn.comX-Ttl: 259200X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.cf0.rackcdn.comX-Cdn-Enabled: TrueX-Log-Retention: FalseX-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.r49.stream.cf0.rackcdn.comX-Trans-Id: tx82a6752e00424edb9c46fa2573132e2cContent-Length: 0

9.3. CDN Object ServicesYou can perform the operation in the following table on objects in your Cloud Filescontainers.





• 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 tokenin Section 3.1.2, “Retrieving the Authentication Token” [10]. Your authentication tokenand your account information are in the service catalog that is produced.


DELETE v1/{account}/{object} Deletes CDN-enabled objects.



94

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 theTTL expires, you can perform a DELETE operation against the object, or you can create asupport ticket to purge the entire container.

Note

You should limit object purges to situations where there could be seriouspersonal, business, or security consequences if it remained publicly accessibleon the CDN (for example, when someone publishs your company's quarterlyearnings 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 toexpire, 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 objectpurges.

If there is already a purge request in progress for an object, a 400 (Bad Request) statuscode is returned with X-Purge-Failed-Reason: That object is already inthe 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 oraddresses. If you want to notify more than one person about the deletion, you can enter acomma-separated list of addresses. The email address is optional.

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) indicatesthat requested CDN-enabled object was not found. Status code 403 (Forbidden) indicatesthat an authorization problem occurred.

The CDN URI is returned in the HTTP header X-Cdn-Uri.



95

Purging objects may take a long time because there are so many edge servers around theglobe. 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.1Host: cdn.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Purge-Email: [email protected], [email protected]

9.3.1.2. Response

Example 9.15. Delete CDN-Enabled Object Response

HTTP/1.1 204 No ContentDate: Thu, 13 Jan 2010 18:57:07 GMTX-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.cf0.rackcdn.comContent-Length: 0Content-Type: text/plain; charset=UTF-8



96

10. Additional CDN Services InformationThe following sections provide additional information about working with the Cloud FilesCDN Services.

10.1. Purge CDN-Enabled ContainersFor 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 thenetwork. After you have made the request to Rackspace through a support ticket, thesystem purges the object from the CDN, and sends an email to the address (or multipleaddresses) 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 SSLA HEAD operation for a CDN-enabled container returns an SSL URI, X-Cdn-Ssl-Uri, inaddition to the other headers associated with CDN. This feature enables you to use httpsprotocol in URIs used for requesting objects stored in CDN-enabled containers.

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) isreturned if the requested container was not found. No content is returned.

Example 10.1. CDN-Enabled Container Metadata Request with SSL


Example 10.2. CDN-Enabled Container Metadata Response with SSL

HTTP/1.1 204 No ContentX-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.comX-Ttl: 259200X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.cf0.rackcdn.comX-Cdn-Enabled: TrueX-Log-Retention: FalseX-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.rackcdn.comX-Trans-Id: tx82a6752e00424edb9c46fa2573132e2cContent-Length: 0



97

10.3. Streaming CDN-Enabled ContainersIn 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 HTTPDynamic Streaming

• X-Cdn-Ios-Uri: specifies the URI for video streaming that uses Apple’s HTTP LiveStreaming (see Section 10.4, “iOS Streaming” [97])

Streaming is a method of relaying data, such as video and audio material, over the networkas a steady continuous stream, allowing playback to proceed while subsequent data isbeing received.

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) isreturned 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 StreamingEnabled


Example 10.4. CDN-Enabled Container Metadata Response with StreamingEnabled

HTTP/1.1 204 No ContentX-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.comX-Ttl: 259200X-Cdn-Ios-Uri: http://fb1ca9de5ff9525ff6f8-64e65126753c56b595824f56d25789bb.iosr.cf1.rackcdn.comX-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.rackcdn.comX-Cdn-Enabled: TrueX-Cdn-Ssl-Uri: https://2cb7edde3eac1dd66ea4-64e65126753c56b595824f56d25789bb.ssl.cf1.rackcdn.comX-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.cf0.rackcdn.coX-Log-Retention: FalseX-Trans-Id: tx82a6752e00424edb9c46fa2573132e2cContent-Length: 0

10.4. iOS StreamingThe Cloud Files CDN allows you to stream video to iOS devices without needing to convertyour video. Once you CDN-enable your container, you have the tools necessary for



98

streaming media to multiple devices. To leverage this ability, you must check the client'sUser Agent with JavaScript. An example of the User Agent check and how to use it is givenbelow.

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 HEADrequest against the CDN-enabled container to view these URIs.

Second, link to your content in a HTML page using a <video> element. Set the SRCattribute of the VIDEO element to the full streaming URI for your container plus the nameof 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 Agentis 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 properlyformatted content for iOS devices only when the iOS streaming URI is used. Here, theJavaScript sets the SRC attribute of the <video> element videotag to the iOS StreamingURI. 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 Agentcheck 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.



99

11. Static Websites Using CDN-EnabledContainers

This chapter describes how to use your CDN-enabled containers to create static websites inCloud Files.

11.1. Create Static WebsiteYou can use your Cloud Files account to create a static website. First, you must CDN-enablea storage container. Any HTML or static web pages in the container become availablethrough a static website once you set the X-Container-Meta-Web-Index header toindex.html or another index page of your choice. You can also create subdirectories inyour website by creating pseudo directories, as outlined in Chapter 6, “Pseudo HierarchicalFolders 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 everysubdirectory in your website. Each of your pseudo directories should contain a file withthat name. So, if you set X-Container-Meta-Web-Index to index.html, you shouldhave an index.html page in each pseudo directory. For example, suppose that you havea subdir pseudo directory. If you do not have an index.html page in subdir, visits tomyhost/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-Listingsheader 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 thelisting.css style sheet. To view the HTML elements to which you can add styles, use yourbrowser to view the HTML source on the listing page.

You can modify the Content-Type of directory marker objects by setting theX-Container-Meta-Web-Directory-Type header. If this header is not set,application/directory is used by default. Directory marker objects are 0-byte objectsthat represent directories to create a simulated hierarchical structure.

The instructions below describe using a CNAME with your DNS Server (or name server). Thisis the domain name of your site (such as www.rackspace.com). Your CNAME is set up withyour individual DNS Server. For more information about using CNAMES, see the Cloud DNSDeveloper Guide at docs.rackspace.com. Once you have your CNAME established, set theCNAME 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.

http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Overview-d1e65.html



100

3. Set the index (or primary page) for your website by performing a POST to the headerX-Container-Meta-Web-Index on your website's container. See the examplebelow. (Remember to change the X-Auth-Token to your authentication token.) Youmust 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 aContainer”.

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 youneed to find your CDN URI, perform a HEAD to cdn.clouddrive.com as shown inSection 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 CNAMErecorded, your static website is ready.

Example 11.2. Container Setup for Static Website

container/index.htmlcontainer/page2.htmlcontainer/subdir/index.htmlcontainer/subdir/pageX.html

In the results below, the CNAME is myhost, and the X-Container-Meta-Web-Index isset to index.html. The results on the right of the example are the pages that display in theWeb browser.

Example 11.3. Static Website Enabled Container Results

http://myhost Displays container/index.htmlhttp://myhost/page2.html Displays container/page2.htmlhttp://myhost/subdir Displays container/subdir/index.htmlhttp://myhost/subdir/ Displays container/subdir/index.htmlhttp://myhost/subdir/pageX.html Displays container/subdir/pageX.html

11.2. Set Error Pages for Static WebsiteYou can create and set custom error pages for visitors to your website. To do this, set themetadata 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 youset. For instance, if you set X-Container-Meta-Web-Error to error.html, 401 errors



101

display the page 401error.html. Similarly, 404 errors display 404error.html. Youmust 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

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Container-Meta-Web-Error: error.html

Any class 200 status codes indicate success.



102

12. Bulk OperationsThis chapter describes bulk operations that are available with Cloud Files.

12.1. Bulk Importing of DataIf you have a very large amount of data to import into Cloud Files, bulk importing ofdata is available. With bulk importing, you send a physical device containing your datato Rackspace and Rackspace loads it directly into Cloud Files. By doing this, you avoid thetime and cost of uploading large amounts of data over the Internet. After the transfer iscomplete, 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 needfor bulk importing in a data center outside of the U.S., contact Rackspacesupport to see what other options you might have. They will be interested inspecifics 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 foldersbecome containers, and nested directory names become part of the object names. Forinstance, Chapter28/Ahab/ivoryleg results in a container named Chapter28 with anobject named Ahab/ivoryleg inside of it. For more information on simulating directorystructures in Cloud Files, see Chapter 6, “Pseudo Hierarchical Folders and Directories” [66].

To begin the bulk import process, contact Rackspace support technicians. You will beassigned a migration specialist who can answer any questions you might have along theway. 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 ArchiveAn extract archive request expands tar files into a Cloud Files account. The request is a PUTwith the query parameter ?extract-archive=format specifying the format of archivefile. Accepted formats are tar, tar.gz, and tar.bz2.

Note

The bulk operation involves middleware that conducts many operations on asingle 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 thefollowing:

http://www.rackspace.com/cloud/files/support/

http://www.rackspace.com/cloud/files/support/



103

• a container

• a pseudo directory within a container

• an empty string

If the UPLOAD_PATH is an empty string, Cloud Files automatically creates containers inwhich to place the files. Files in the base directory of the tar file (that is, files that are notin 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 thatonly regular files are uploaded. Objects such as empty directories and symlinks are notuploaded.

The responses from bulk operations are not like other Cloud Files responses because ashort request body sent from the client could result in many operations on the proxy serverand precautions need to be made to prevent the request from timing out due to a lack ofactivity. To this end, the client always receives a 200 OK response, regardless of the actualsuccess of the call. The body of the response, which can be delivered over a greater amountof time, must be parsed to determine the actual success of the operation. In addition, theclient may receive whitespace characters prepended to the response body while the proxyserver is completing the request.

The format of the response body defaults to text plain but can be either JSON or XMLdepending on the Accept header. Acceptable formats are text/plain, application/json, application/xml, and text/xml. The following example shows the responsebody, formatted in JSON, from a successful request.

Example 12.1. Extract Archive Response

HTTP/1.1 100 Continue

HTTP/1.1 200 OKContent-Type: application/jsonX-Trans-Id: txa7fd1603cfe04bdb920cd-005191226dDate: Mon, 13 May 2013 17:27:10 GMTTransfer-Encoding: chunked

{ "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




104

HTTP/1.1 200 OKContent-Type: application/jsonX-Trans-Id: tx9f12e16f047049cc91147-005191245fDate: Mon, 13 May 2013 17:35:27 GMTTransfer-Encoding: chunked

{ "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. TheerrorResponse is the failing HTTP status of the response for that individual PUT. After1,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 is201 Created. If any files failed to be created, the Response Status corresponds to thesubrequest's error. Possible codes are 400, 401, and 502. In both cases, the response bodyspecifies the number of files successfully uploaded and a list of the files that failed. (Theactual HTTP status code is always 200 OK, so the response code in the response body is theone 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 toa blank string, Cloud Files determines the Content-Type based on theindividual file type. For example, if you have MIME type files, use a blank stringfor Content-Type to set the MIME type for files within the archive.

12.3. Bulk DeleteBulk Delete request deletes multiple objects or containers from an account with a singlerequest. 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, “ServiceAccess 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 asingle request.

The objects specified in the DELETE request body must be URL-encoded and in the form:



105

/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 200OK and the response body must be parsed for actual results. The following example showsthe response body, formatted in JSON, from a successful request.

Example 12.3. Bulk Delete Response


HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8X-Trans-Id: tx52fe4601dde24e2b8e7cb-0051912ca8Date: Mon, 13 May 2013 18:10:48 GMTTransfer-Encoding: chunked

{ "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 OKContent-Type: application/json; charset=UTF-8X-Trans-Id: tx28552a8cd9cb441dad3ad-0051912d2dDate: Mon, 13 May 2013 18:13:01 GMTTransfer-Encoding: chunked

{ "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 anyfailed to delete, the status code corresponds to the subrequest's error. Possible codesare 400, 401, and 502. In all cases, the Response Body specifies the number of itemssuccessfully deleted or not found as well as a list of those that failed. The return body is



106

formatted in the way specified in the request's Accept header. Acceptable formats aretext/plain, application/json, application/xml, and text/xml.

The list of errors is a list of tuples in the form [objectPath, errorResponse]. TheobjectRath is the full path of where the object (or container) was to be deleted. TheerrorResponse is the failing HTTP status of the response for that individual DELETE.



107

13. Public Access to Your Cloud FilesAccount

This section describes ways that you can allow others to put or retrieve objects from yourCloud Files account. With the methods described here, users do not need your password orlogin information in order to have access to your account.

13.1. TempURLThe Temporary URL feature (TempURL) allows you to create limited-time Internetaddresses that allow you to grant limited access to your Cloud Files account. UsingTempURL, you can allow others to retrieve or place objects in your Cloud Files account fora specified amount of time. Access to the TempURL is independent of whether or not youraccount is CDN-enabled. And even if you do not CDN-enable a directory, you can still granttemporary public access through a TempURL.

This feature is useful if you want to allow a limited audience to download a file from yourCloud Files account or website. You provide a TempURL and after a specified time, no onewill be able to access that object using the TempURL. Or, if you want to allow others toupload objects into your Cloud Files account, you can give them a TempURL. After thespecified time expires, no one will be able to upload to the address.

Additionally, you need not worry about time running out when someone downloads alarge object. If the time expires while a file is being retrieved, the download will continueuntil 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 theTempURL metadata key described in the next section. The TempURL is theactual URL.

13.1.1. Set Account TempURL Metadata KeyTo 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 anyarbitrary 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 accessyour TempURL. If you change it, the TempURL becomes invalid (within 60 seconds, which isthe cache time for a key) and others will not be allowed to access it.

Example 13.1. Set Account Metadata Key for Public Access

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-Account-Meta-Temp-Url-Key: yourKey



108

Any class 200 status code indicates success.

13.1.2. Create the TempURLAfter the metadata is set, you must create an HMAC-SHA1 (RFC 2104) signature. When yougenerate the TempURL, you determine which method of access you will grant users, GETor 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 beavailable 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 da39a3ee5e6b4b0d3255bfef95601890afd80709and the expire time might translate to 1323479485 because the signature and expirescompletely depend on the time when the code runs. On your website, you would provide alink 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) statuscode. HEAD queries are allowed if GET or PUT are allowed.

Example 13.3. Create TempURL (in PHP)



109

<?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-Dispositionheader and indicate to the browser a file name in which to save the file. In the followingexample, you see the usual TempURL without the file name override.



110

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 toindicate 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. FormPostFormPost lets you offer your website audience a way to upload objects to your Cloud Filesaccount through a web form. FormPost works by translating a browser form request into aobject PUT in Cloud Files. Once you enable FormPost on your account, you need only createthe 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 uploadan 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 metadataheader X-Account-Meta-Temp-Url-Key on your Cloud Files account to a key that onlyyou 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 isthe cache time for a key).

Example 13.7. Set Account Metadata Key for Public Access Request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: f064c46a782c444cb4ba4b6434288f7cX-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 usingthe following format in your website:



111

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 willbe 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 thefront of it.

Note

You can also include a prefix to separate uploads, such as assigning each usera 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 websiteafter the form processes. The URL will have status and message query parameters addedto it, indicating the HTTP status code for the upload (2xx indicates success) and a possiblemessage 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 HMACbody.

Required: The max_file_size attribute must be included and specifies the maximumsize in bytes of a single file. However, the storage system maximum file size is 5 GB, somax_file_size cannot exceed 5 GB.

Required: The max_file_count attribute indicates the maximum number of files that canbe uploaded with the form.

Required: The expires attribute is the Unix timestamp when the form is invalidated. Thisgives your website users a limited time to have the form open. Time must be in Unix epochformat.

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 issample code for computing the signature in Python:



112

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 theform.

The key value is the value of the X-Account-Meta-Temp-Url-Key header set for theaccount.

The max_file_count value used to generate the signature must be the same as thatin the web form.

Required: The type="file" field defines the form file field. At least one entry is requiredto allow your users to select and upload a file, but additional fields may be added formultiple 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 forCloud Files to process the uploads properly.

13.3. CORSCross-Origin Resource Sharing (CORS) is a mechanism to allow code running in a browser tomake requests to a domain other than the one from which it originated. CORS containerheaders allow your users to upload files from one website, or origin, to your Cloud Filesaccount. When you set the CORS headers on your container, you provide Cloud Files withthe 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:



113

• 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 givenURL

Cloud Files supports CORS requests to containers and objects. CORS metadata is held on thecontainer 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-Origin

Origins allowed to make Cross Origin requests,separated by a space when there are multiples.

X-Container-Meta-Access-Control-Max-Age Maximum age for the Origin to hold the preflightresults, in seconds (for example, 5, 10, or 1000).

X-Container-Meta-Access-Control-Expose-Headers

Headers exposed to the browser in the actual requestresponse, separated by a space when there aremultiples.

Before a browser issues an actual request, it might issue a preflight request. The preflightrequest 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 headerslisted in the X-Container-Meta-Access-Control-Expose-Headers header. Bydefault, 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) youwill 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 hostingthis container should have CORS support.)

http://www.w3.org/TR/cors/#simple-response-header/



114

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 didnot 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">



115

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>



116

14. Examples and TroubleshootingThis section introduces the cURL command-line utility and demonstrates interacting withthe 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, anobject name of C++final(v2).txt should be URL-encoded as C%2B%2Bfinal%28v2%29.txtand 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 onlywhen the one you have is expired.

14.1. Using cURLcURL is a command-line tool that you can use to interact with REST interfaces. cURL letsyou to transmit and receive HTTP requests and responses from the command line or a shellscript, 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 moreinformation 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 cURLIn order to use the REST API, you will first need to obtain an authorization token, which willneed 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 tokenand the URL of the storage system. Note that your account may be based in either theUS or the UK. This is not determined by your physical location, but by the location of theRackspace 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 KeyCredentials 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"

http://curl.haxx.se/



117

{ "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 theresponse. After authentication, you can use cURL to perform GET, HEAD, DELETE, POSTand PUT requests on the storage and CDN services.

While an authentication token lasts, you can continue to perform requests. However, oncea token expires, it will return an HTTP status code 401 (Unauthorized). Given that a token isgood 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:



118

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-Tokenheader with the authentication token obtained in Step 1.

3. Repeat step 2 using the same authentication token retrieved in Step 1 until either thejob 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 newauthentication 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 anerror can be found in the OpenStack Swift project in client.py, which is freely available.

14.3. Determining Storage Usage with cURLA HEAD request can be sent to the storage service to determine how much data youhave stored in the system and the number of containers you are using. Use the -X switchto specify the correct HTTP method and the -D to dump the HTTP response headers toterminal 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

HTTP/1.1 204 No Content X-Account-Object-Count: 4943 X-Account-Bytes-Used: 25603957646 X-Account-Container-Count: 151 Accept-Ranges: bytes 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 HTTPheaders in the response indicate the number of containers in this storage account and thetotal bytes stored for the entire account.

14.4. Creating a Storage Container with cURLBefore uploading any data to Cloud Files, you must create a storage container. You do thiswith a PUT request. cURL can be used for that, too.

Example 14.3. cURL Create Storage Container

curl -X PUT -D - \ -H "X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c" \



119

https://storage.clouddrive.com/v1/CF_xer7_343/images

HTTP/1.1 201 Created Content-Length: 18 Content-Type: text/html; charset=UTF-8 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 wassuccessfully created.

14.5. Uploading a Storage Object with cURLAfter creating a container, you can upload a local file. For this example, upload ascreenshot image. The -T switch specifies the full path to the local file to upload. Pleasenote that if you intend to distribute this object through the CDN you MUST make sure thatthe object's Content-Type is set correctly. This is the mechanism by which a user's webbrowser 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-Auth-Token: f064c46a782c444cb4ba4b6434288f7c" \ -H "X-Object-Meta-Screenie: Mel visits Outland" \ https://storage.clouddrive.com/v1/CF_xer7_343/images/wow1.jpg

HTTP/1.1 201 Created 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 cURLAfter creating a container and storing a file in it, you can choose to share the file. Since thedata 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 defaultTTL is 72 hours and supports a minimum of 15 minutes (900 seconds) and a maximum of50 years (1577836800 seconds). Note that the target URL specifies the CDN system, not theauthorization system.

Note

On August 13, 2012, the maximum TTL was set to 31536000 (one year). Ifyou set new TTL values to a greater time frame, your object will still expire at



120

the one-year mark. However, if you already had a greater TTL value set on anobject, it will expire at the time you had originally set.

Example 14.5. cURL CDN-Enable Container

curl -X PUT -D - \ -H "X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c" \ -H "X-CDN-Enabled: True" \ -H "X-TTL: 259200" \ https://cdn.clouddrive.com/v1/CF_xer7_343/images

HTTP/1.1 204 No Content 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

When the container is CDN-enabled, the service returns its public URL in the X-CDN-URIheader 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, oruse the https:// URL in combination with the object name to access the file over a secureSSL connection through the CDN.

You can verify the CDN's cache settings that you specified with your TTL value by sendinga GET request to the object's CDN URL and viewing the response headers. The TTL valueyou specify translates to the Expires and Cache-Control headers of the CDN's cachedObject.

The cURL command below issues a GET request which downloads the entire file but writesit to /dev/null, a data sink that will not actually save the content to your local drive (thisconvention 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



121

Last-Modified: Thu, 09 Jul 2009 17:14:46 GMT Cache-Control: max-age=86400, public ETag: b20237bff6828976d2eb348e1ca8adae Content-Length: 1255764 Content-Type: image/jpeg Connection: keep-alive

14.7. Other cURL CommandsYou can issue any of the REST methods defined for Cloud Files with the cURL utility. Forexample, you can use cURL to send POST and DELETE requests even though no specificexamples 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 thereforeprovide much better performance. We recommend that you use one of the language APIsin your production applications and limit curl to quick-and-easy testing/troubleshooting.



122

GlossaryAccount

The Cloud Files system is designed to be used by many different customers. Your user account isyour slice of the Cloud Files system. You must identify yourself with a valid user name and yourAPI access key. Once authenticated, your have full read/write access to the objects (files) storedunder your account.

Application program interface (API)A set of routines, protocols, and tools for building software applications. A good API makes iteasier to develop a program by providing all the building blocks. A programmer then puts theblocks together.

AuthenticationAuthentication requires getting an authentication token by using the Rackspace Cloud Identityservice. While the authentication token is valid (which in most cases is 24 hours), you must pass itto Cloud Files to perform all Cloud Files operations.

CDN-enabled containersTo publish your data so that it can be served by Akamai's content delivery network (CDN), youneed 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 forread access. However, uploading content into a CDN-enabled container is a secure operationand requires a valid authentication token. Each published container has a unique URL thatcan be combined with its object name and openly distributed in web pages, emails, or otherapplications. For example, a CDN-enabled container named photos can be referenced ashttp://c0344252.cdn.cloudfiles.rackspacecloud.com. If that container houses animage called cute_kids.jpg, that image can be served by Akamai's CDN with the full URL ofhttp://c0344252.cdn.cloudfiles.rackspacecloud.com/cute_kids.jpg.

ContainerA storage compartment that provides a way for you to organize data. A container is similar to afolder in Windows or a directory in UNIX. The primary difference between a container and theseother 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 deliverwebpages and other Web content to a user based on the geographic locations of the user, theorigin of the webpage, and a content delivery server.

Language-specific APILanguage-specific APIs in several popular languages are available to help put Cloud Files in thehands 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 directlywith HTTP requests and responses.

MiddlewareSoftware that connects two otherwise separate applications. For example, there are a number ofmiddleware products that link a database system to a Web server.



123

OperationsOperations are the actions you perform against your account in Cloud Files, such as creating ordeleting containers, uploading or downloading objects, etc. Operations are performed via theREST web service API or a language-specific API.

PermissionsThere are no permissions or access-controls for containers or objects other than being split intoseparate accounts. You must authenticate with a valid API access key, but once authenticated youcan create and delete containers and objects only within that account.

Private containerA private container is a container that is only accessible by the account holder.

Public containerA public container is a CDN-enabled container that is publicly accessible.

RESTREST, short for Representational State Transfer, is an architectural style for large-scale softwaredesign.

Documents

Rackspace Cloud Files - Developer Guide