Cloud Files™ Developer Guide - Rackspace Manuals

mealpythonInternet and Web Development

Nov 3, 2013 (3 years and 9 months ago)

207 views

docs.rackspace.com/api
Cloud Files™ Developer Guide
November 1, 2013
API v1
ii
Cloud Files™ Developer Guide
API v1 (2013-11-01)
Copyright © 2009-2013 Rackspace US, Inc. All rights reserved.
This document is intended for software developers interested in developing applications using the Rackspace Cloud Files™ Application
Programming Interface (API). The document is for informational purposes only and is provided “AS IS.”
RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR
COMPLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND
PRODUCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE
WITHOUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT
AS SET FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO
LIABILITY WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any
license to patents, trademarks, copyrights, or other intellectual property.
Rackspace®, Rackspace logo and Fanatical Support® are registered service marks of Rackspace US, Inc. All other product names and
trademarks used in this document are for identification purposes only and are property of their respective owners.
Cloud Files™ Developer Guide
November 1, 2013
API v1
iii
Table of Contents
1. Overview ..................................................................................................................... 1
1.1. Intended Audience ........................................................................................... 1
1.2. Document Change History ................................................................................ 2
1.3. Additional Resources ........................................................................................ 3
1.4. Pricing and Service Level ................................................................................... 4
2. Concepts ..................................................................................................................... 5
2.1. Accounts .......................................................................................................... 5
2.2. Authentication ................................................................................................. 5
2.3. Permissions ....................................................................................................... 5
2.4. Containers ........................................................................................................ 5
2.5. Objects ............................................................................................................. 6
2.6. Operations ....................................................................................................... 6
2.7. CDN-Enabled Containers ................................................................................... 7
2.8. Language-Specific API Bindings ......................................................................... 8
3. General API Information ............................................................................................. 9
3.1. Authentication ................................................................................................. 9
3.1.1. Geographic Endpoints ............................................................................ 9
3.1.2. Retrieving the Authentication Token ...................................................... 9
3.2. Role Based Access Control .............................................................................. 18
3.2.1. Assigning Roles to Account Users ......................................................... 18
3.2.2. Roles Available for Cloud Files .............................................................. 18
3.2.3. Resolving Conflicts Between RBAC Multiproduct vs. Custom (Product-
specific) Roles ................................................................................................ 19
3.2.4. RBAC Permissions Cross-reference to Cloud Files API Operations ............ 19
3.3. Service Access Endpoints ................................................................................. 19
4. Overview of API Operations ...................................................................................... 21
5. API Operations for Storage Services ........................................................................... 23
5.1. Storage Account Services ................................................................................ 23
5.1.1. View Account Details ........................................................................... 23
5.1.2. List Containers ..................................................................................... 24
5.2. Storage Container Services .............................................................................. 27
5.2.1. View Container Details ......................................................................... 28
5.2.2. Create Container ................................................................................. 28
5.2.3. Delete Container .................................................................................. 33
5.2.4. Set or Edit Container Metadata ........................................................... 33
5.2.5. List Objects in a Container ................................................................... 34
5.2.6. Container Quotas ................................................................................ 38
5.2.7. Access Log Delivery .............................................................................. 38
5.3. Storage Object Services .................................................................................. 39
5.3.1. Retrieve Object .................................................................................... 39
5.3.2. Create/Update Object .......................................................................... 40
5.3.3. Copy Object ......................................................................................... 49
5.3.4. Delete Object ...................................................................................... 51
5.3.5. Retrieve Object Metadata .................................................................... 51
5.3.6. Update Object Metadata ..................................................................... 52
5.3.7. Bulk Operations (Delete and Archive Auto Extraction) .......................... 53
6. API Operations for CDN Services ............................................................................... 57
6.1. CDN Account Services ..................................................................................... 57
Cloud Files™ Developer Guide
November 1, 2013
API v1
iv
6.1.1. List CDN-Enabled Containers ................................................................ 57
6.2. CDN Container Services .................................................................................. 60
6.2.1. CDN-Enable a Container ....................................................................... 60
6.2.2. List a CDN-Enabled Container's Metadata ............................................. 62
6.2.3. Purge CDN-Enabled Containers ............................................................ 63
6.2.4. Update CDN-Enabled Container Metadata ........................................... 63
6.2.5. CDN-Enabled Containers Served through SSL ........................................ 64
6.2.6. Streaming CDN-Enabled Containers ...................................................... 64
6.2.7. iOS Streaming ...................................................................................... 65
6.3. CDN Object Services ....................................................................................... 66
6.3.1. Purge CDN-Enabled Objects ................................................................. 67
6.4. Static Web Services ......................................................................................... 67
6.4.1. Create Static Website ........................................................................... 68
6.4.2. Set Error Pages for Static Website ........................................................ 69
7. Public Access to Your Cloud Files Account .................................................................. 71
7.1. TempURL ........................................................................................................ 71
7.1.1. Set Account Temp URL Metadata Key .................................................. 71
7.1.2. Create the TempURL ............................................................................ 72
7.1.3. Override TempURL File Names ............................................................. 73
7.2. FormPost ........................................................................................................ 74
7.2.1. Set Account Metadata Key .................................................................. 74
7.2.2. Create the Form .................................................................................. 74
7.3. CORS .............................................................................................................. 76
8. Examples and Troubleshooting .................................................................................. 80
8.1. Using cURL ..................................................................................................... 80
8.2. Authentication with cURL ............................................................................... 80
8.3. Determining Storage Usage with cURL ............................................................ 82
8.4. Creating a Storage Container with cURL ......................................................... 82
8.5. Uploading a Storage Object with cURL ........................................................... 83
8.6. CDN-Enabling the Container with cURL ........................................................... 83
8.7. Other cURL Commands ................................................................................... 85
Glossary ......................................................................................................................... 86
Cloud Files™ Developer Guide
November 1, 2013
API v1
v
List of Figures
4.1. Cloud Files System Interfaces .................................................................................. 22
Cloud Files™ Developer Guide
November 1, 2013
API v1
vi
List of Tables
3.1. Cloud Files Product Roles and Permissions ............................................................... 18
3.2. Multiproduct (Global) Roles and Permissions ........................................................... 19
3.3. Regionalized Service Endpoints ............................................................................... 19
5.1. Metadata Values for Setting Container Quotas ....................................................... 38
7.1. Supported CORS Container Headers ....................................................................... 77
Cloud Files™ Developer Guide
November 1, 2013
API v1
vii
List of Examples
3.1. Auth Request: XML ................................................................................................ 10
3.2. Auth Request: JSON ............................................................................................... 10
3.3. Auth Response: XML .............................................................................................. 10
3.4. Auth Response: JSON ............................................................................................. 12
5.1. Storage Account HTTP Request: General Structure .................................................. 23
5.2. View Account Information Request ........................................................................ 24
5.3. View Account Information Response ...................................................................... 24
5.4. View Containers List Request .................................................................................. 24
5.5. View Containers List Response ................................................................................ 24
5.6. Container Details Request: JSON ............................................................................. 25
5.7. Container Details Response: JSON ........................................................................... 25
5.8. Container Details Request: XML .............................................................................. 25
5.9. Container Details Response: XML ............................................................................ 25
5.10. List Large Number of Containers ........................................................................... 26
5.11. Storage Container HTTP Request: General Structure .............................................. 27
5.12. View Container Details Request ............................................................................ 28
5.13. View Container Details Response .......................................................................... 28
5.14. Container Create Request ..................................................................................... 28
5.15. Container Create Response ................................................................................... 29
5.16. Container Create Request with Metadata ............................................................. 29
5.17. Container Create Response ................................................................................... 29
5.18. Example of Multi-region Data Center Endpoints from the Service Catalog .............. 30
5.19. Pseudo-Hierarchical Folders/Directories ................................................................. 32
5.20. Container Delete Request ..................................................................................... 33
5.21. Container Delete Response ................................................................................... 33
5.22. Update Container Metadata Request .................................................................... 34
5.23. Update Container Metadata Response .................................................................. 34
5.24. View Container Metadata Request ....................................................................... 34
5.25. View Container Metadata Response ..................................................................... 34
5.26. Objects List Request .............................................................................................. 35
5.27. Objects List Response ........................................................................................... 35
5.28. Object Details Request: JSON ................................................................................ 35
5.29. Object Details Response: JSON .............................................................................. 36
5.30. Object Details Request: XML ................................................................................. 36
5.31. Object Details Response: XML ............................................................................... 36
5.32. List Large Number of Objects ............................................................................... 37
5.33. Example Access Log Entries ................................................................................... 39
5.34. Retrieve Object Request ........................................................................................ 40
5.35. Retrieve Object Response ..................................................................................... 40
5.36. Create/Update Object Request ............................................................................. 41
5.37. Create/Update Object Response ........................................................................... 41
5.38. Upload Segment of a Large Object Request .......................................................... 42
5.39. Upload Segment of a Large Object Response ........................................................ 42
5.40. Upload Next Segment of the Large Object Request ............................................... 42
5.41. Upload Next Segment of the Large Object Response ............................................. 42
5.42. Upload Manifest Request ...................................................................................... 43
5.43. Upload Manifest Response ................................................................................... 43
5.44. Upload Unspecified Quantity of Content ............................................................... 45
Cloud Files™ Developer Guide
November 1, 2013
API v1
viii
5.45. Content-Encoding Header Example ....................................................................... 46
5.46. Content-Disposition Header Example .................................................................... 47
5.47. Delete At Example ................................................................................................ 47
5.48. Delete After Example ........................................................................................... 48
5.49. Object Versioning with cURL ................................................................................. 49
5.50. Data Center Endpoints ......................................................................................... 50
5.51. Object Delete Request .......................................................................................... 51
5.52. Object Delete Response ........................................................................................ 51
5.53. Object Metadata Request ..................................................................................... 51
5.54. Object Metadata Response ................................................................................... 52
5.55. Update Object Metadata Request ......................................................................... 52
5.56. Update Object Metadata Response ....................................................................... 53
5.57. Extract Archive Response ...................................................................................... 54
5.58. Extract Archive Response with Errors .................................................................... 54
5.59. Bulk Delete Response ........................................................................................... 55
5.60. Bulk Delete Response with Errors .......................................................................... 55
6.1. CDN HTTP Request: General Structure .................................................................... 57
6.2. CDN-Enabled Containers List Request ...................................................................... 58
6.3. CDN-Enabled Containers List Response ................................................................... 58
6.4. CDN-Enabled Containers Details Request: JSON ....................................................... 58
6.5. CDN-Enabled Containers Details Response: JSON ..................................................... 58
6.6. CDN-Enabled Containers Details Request: XML ........................................................ 59
6.7. CDN-Enabled Containers Details Response: XML ...................................................... 59
6.8. CDN-Enabled Container HTTP Request: General Structure ........................................ 60
6.9. Container CDN-Enable Request ............................................................................... 61
6.10. Container CDN-Enable Response ........................................................................... 61
6.11. Container CDN-Disable Request ............................................................................ 61
6.12. CDN-Enabled Container Metadata Request ........................................................... 62
6.13. CDN-Enabled Container Metadata Response ......................................................... 62
6.14. Update CDN-Enabled Container Metadata Request ............................................... 63
6.15. Update CDN-Enabled Container Metadata Response ............................................. 63
6.16. CDN-Enabled Container Metadata Requests with SSL ............................................ 64
6.17. CDN-Enabled Container Metadata with SSL ........................................................... 64
6.18. CDN-Enabled Container Metadata Requests (Streaming Enabled) .......................... 64
6.19. CDN-Enabled Container Metadata (Streaming Enabled) ........................................ 65
6.20. HTML 5 Video Element ......................................................................................... 65
6.21. JavaScript for User Agent Check ........................................................................... 66
6.22. Load JavaScript in HTML page .............................................................................. 66
6.23. Purge CDN-Enabled Object ................................................................................... 67
6.24. Purge CDN-Enabled Object Response .................................................................... 67
6.25. Set up Static Web ................................................................................................. 69
6.26. Container Setup for Static Web Site ...................................................................... 69
6.27. Static Web Site Enabled Container Results ............................................................. 69
6.28. Set Error Pages for Static Website ......................................................................... 69
7.1. Set Account Metadata Key for Public Access ........................................................... 71
7.2. Create TempURL (in python) .................................................................................. 72
7.3. Create TempURL (in PHP) ....................................................................................... 73
7.4. Create TempURL (in Ruby) ..................................................................................... 73
7.5. TempURL without File Name Override .................................................................... 74
7.6. TempURL with File Name Override ......................................................................... 74
7.7. Set Account Metadata Key for Public Access ........................................................... 74
Cloud Files™ Developer Guide
November 1, 2013
API v1
ix
7.8. Layout of Web Form .............................................................................................. 75
7.9. Generate Signature for Form Post .......................................................................... 76
7.10. CORS POST Request .............................................................................................. 77
7.11. Test CORS Page .................................................................................................... 78
8.1. cURL Authenticate Request with Username and API Key Credentials and
Response:JSON .............................................................................................................. 80
8.2. cURL Get Storage Space ......................................................................................... 82
8.3. cURL Create Storage Container ............................................................................... 83
8.4. cURL Upload Storage Object .................................................................................. 83
8.5. cURL CDN-Enable Container .................................................................................... 84
8.6. cURL Download a File ............................................................................................. 84
Cloud Files™ Developer Guide
November 1, 2013
API v1
1
1. Overview
Rackspace Cloud Files™ is an affordable, redundant, scalable, and dynamic storage service
offering. The core storage system is designed to provide a safe, secure, automatically re-
sizing and network-accessible way to store data. You can store an unlimited quantity of
files and each file can be as large as 5 gigabytes. Users can store as much as they want and
pay only for storage space they actually use.
Additionally, Cloud Files provides a simple yet powerful way to publish and distribute
content behind a Content Distribution Network. Cloud Files users get access to this network
automatically without having to worry about contracts, additional costs, or technical
hurdles.
Cloud Files allows users to store and retrieve files and CDN-enabled content through
a simple Web Service interface (REST: Representational State Transfer). There are also
language-specific APIs that utilize the RESTful API but make it much easier for developers to
integrate into their applications.
For more details on the Cloud Files service, please refer to http://www.rackspace.com/
cloud/files/ and to the Knowledge Center article Best Practices for Using Cloud Files.
We welcome feedback, comments, and bug reports at support@rackspacecloud.com.
1.1. Intended Audience
This guide is intended to assist software developers who want to develop applications
using the Rackspace Cloud Files API. It fully documents the REST application programming
interface (API) that allows developers to interact with the storage and CDN components
of the Cloud Files system. To use the information provided here, you should first have a
general understanding of the Rackspace Cloud Files service and have access to an active
Rackspace Cloud Files account. You should also be familiar with:
• RESTful web services
• HTTP/1.1
Rackspace also provides language-specific APIs in several popular programming languages.
Currently, the APIs are C#/.NET, Java, PHP, Python, and Ruby. These APIs utilize the REST
API and are provided to help developers rapidly integrate Cloud Files support into their
applications without needing to write to the REST interface. Each API includes its own
documentation in its native format. For example, the Java API includes JavaDocs and the
C#/.NET API includes a CHM file.
System administrators and other users interested in the storage and CDN benefits of Cloud
Files should consider using the File Manager interface within the Rackspace Cloud Control
Panel, Jungle Disk, or third party tools such as Fileuploader or Cyberduck. The Control Panel
provides an easy to use web-based interface for uploading and downloading content to
and from Cloud Files.
For additional information about available language bindings, refer to the section,
Language-Specific API Bindings.
Cloud Files™ Developer Guide
November 1, 2013
API v1
2
1.2. Document Change History
This version of the Developer Guide replaces and obsoletes all previous versions. The most
recent changes are described in the table below:
Revision Date
Summary of Changes
November 1, 2013
• Replaced references to X-Storage-Url and X-CDN -ManagementUrl throughout
this document with references to the cloudFiles and cloudFilesCDN endpoints in the
service catalog based on use of Identity v2.0 rather than Identity v1.0.
• Updated Section 2.2, “Authentication” [5] to include new references to additional
information about the service access endpoints and the service catalog.
• Updated Section 8.2, “Authentication with cURL” [80] to show a cURL example for
Identity v2.0 only.
October 25, 2013
• Added Section 3.3, “Service Access Endpoints” [19], which includes all endpoints for
Cloud Files including the newest one in Hong Kong.
• Updated Section 5.2.2.1, “Multi-region Support” [29] to include additional endpoints
from the service catalog.
• Updated Section 3.1, “Authentication” [9] to show information for Rackspace Identitfy
v2.0.
• Updated Section 7.2.2, “Create the Form” [74] 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” [18].
• Updated Section 7.3, “CORS ” [76].
September 19, 2013
• Updated responses to show application/json in Section 5.3.7.2, “Bulk Delete” [55].
• Added X-Container-Meta-Web-Listings, X-Container-Meta-Web-Listings-CSS, and X-Container-
Meta-Web-Directory-Type to Section 6.4.1, “Create Static Website” [68].
July 18, 2013
• Clarified information about redirect and expires in Section 7.2.2, “Create the
Form” [74].
July 2, 2013
• Corrected Example 7.1 (back to using Identity v1.0) in Section 8.2, “Authentication with
cURL” [80] and added an example for Identity v2.0.
June 27, 2013
• In Section 3.1, “Authentication” [9], changed references for authentication to point to
v2.0.
• In Section 8.2, “Authentication with cURL” [80], updated the example to show v2.0 for
authentication.
• In Section 6.3.1, “Purge CDN-Enabled Objects” [67] and Section 6.2.3, “Purge CDN-
Enabled Containers” [63], 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” [9].
May 20, 2013
• Added a link in Chapter 1, “Overview” [1] to the Knowledge Center article, "Best Practices
for Using Cloud Files," at http://www.rackspace.com/knowledge_center/article/best-
practices-for-using-cloud-files.
• Added Section 5.2.6, “Container Quotas” [38]
• Created a new section Section 5.3, “Storage Object Services” [39]. This section includes
new and previously existing information specifically related to storage objects.
• Added Section 5.3.2.2, “Static Large Object (SLO) Creation” [43].
• Added Section 5.3.7, “Bulk Operations (Delete and Archive Auto Extraction)” [53].
• Added Section 7.1.3, “Override TempURL File Names” [73].
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.
Cloud Files™ Developer Guide
November 1, 2013
API v1
3
Revision Date
Summary of Changes
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.
February 6, 2012
• Revisions to clarify issues brought up in doc tickets. Formatted HEAD like other commands.
Standardized on URL. Added Expiring Objects and ServiceNet information.
January 12, 2012
• Revisions for the addition of expiring object functionality plus doc bug fixes including adding
more cross-references for finding language bindings.
November 15, 2011
• Revised information about how to perform a CDN purge, indicating you must contact
support to request a container purge operation.
October 21, 2011
• Added more detail about reasons to perform a CDN purge, clarifying that it is not required
for deleting objects.
September 13, 2011
• Added information about streaming containers to support this new streaming feature,
including changing examples to match the streaming headers and URLs returned.
June 29, 2011
• In the 6.1.1 Authorization example, changed X-Auth-Token to X-Auth-Key.
June 15, 2011
• Added best practices for authentication tokens.
May 24, 2011
• Added information about new headers including CORS headers.
April 20, 2011
• HEAD returns 200 instead of 204 on an object metadata request.
• TTL maximum value is now 50 years instead of 3 days, the minimum TTL is now 15 minutes
(900 seconds), and the default is now 72 hours instead of 24 hours.
March 25, 2011
• Added information about large object support.
March 17, 2011
• Added information about container metadata.
March 10, 2011
• Added a section about retrieving an SSL URL for CDN-enabled containers that are using
https protocol.
• Updated examples to contain SSL as appropriate.
February 25, 2011
• Added information about the edge purge capability for CDN-enabled containers and
objects.
February 18, 2011
• Fixed error in the header range example that stated first instead of last when fetching a
portion of the data.
• Updated CDN URLs to match new format.
• Fixed error referring to X-Auth-User instead of X-Auth-Key.
January 12, 2011
• Removed references to ACL (Access Control List).
• Fixed error in examples referring to X-Auth-Key where it should be X-Auth-Token.
• Added section numbers.
January 4, 2011
• Expanded authentication information for UK release.
• Added delimiter as a Query Parameter and server-side object copy example.
May 5, 2008
• Initial release.
1.3. Additional Resources
You can download the most current version of this document from the Rackspace Cloud
website at docs.rackspacecloud.com/files/api/cf-devguide-latest.pdf.
Cloud Files™ Developer Guide
November 1, 2013
API v1
4
For more details about the Cloud Files service, please refer to http://www.rackspace.com/
cloud/files/. Related documents are available at the same site, as are links to official
Rackspace support channels, including knowledge base articles, forums, phone, chat, and
email.
Language bindings are available. Each binding includes its own documentation (either
HTML, PDF, or CHM). They also include code snippets and examples to help you get
started. The API bindings for Cloud Files are:
• PHP (requires 5.x and the modules: cURL, FileInfo, mbstring)
• Python (requires 2.4 or newer)
• Java (requires JRE v1.5 or newer)
For additional information about available language bindings, refer to Language-Specific
API Bindings.
1.4. Pricing and Service Level
Cloud Files is part of the Rackspace Cloud and your use through the API will be billed as per
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?page=files.
Cloud Files™ Developer Guide
November 1, 2013
API v1
5
2. Concepts
Cloud Files is not a file system in the traditional sense. You will not be able to map or
mount virtual disk drives like you can with other forms of storage such as a SAN or NAS.
Since Cloud Files is a different way of thinking when it comes to storage, you should take a
few moments to review the key concepts listed below.
2.1. Accounts
The Cloud Files system is designed to be used by many different customers. Your user
account is your portion of the Cloud Files system. A user must identify themselves with
their Rackspace Cloud username and API Access Key and once authenticated, that user
has full read/write access to the files stored under that user account. Please visit http://
www.rackspacecloud.com/signup to obtain a Cloud Files account and enable your API
Access Key.
2.2. Authentication
Section 3.1, “Authentication” [9] describes how to authenticate against the
Authentication service to receive Cloud Files connection parameters and an authentication
token. The token must be passed in for all subsequent container/object operations during
the time it is valid.
See the following sections for more information:
• Section 3.3, “Service Access Endpoints” [19] shows the service access endpoints for
Cloud Files.
• Example 5.18, “Example of Multi-region Data Center Endpoints from the Service
Catalog” [30] shows service catalog information for Cloud Files.
For more information about authentication, see the Cloud Identity Client Developer Guide,
v2.0 at docs.rackspace.com.
Note
The language-specific APIs handle authentication, token passing, and HTTPS
request/response communication.
2.3. Permissions
In Cloud Files, each user has their own storage account and has full access to that account.
Users must authenticate with their credentials as described above, but once authenticated
they can create/delete containers and objects within that account.
2.4. Containers
A container is a storage compartment for your data and 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®.
Cloud Files™ Developer Guide
November 1, 2013
API v1
6
The primary difference between a container and these other file system concepts is
that containers cannot be nested. You can, however, create up to 500,000 containers
within your account. Data must be stored in a container so you must have at least one
container defined in your account prior to uploading data. If you expect to have containers
with millions of objects, we recommend organizing the object storage across multiple
containers.
The only restrictions on container names is that they cannot contain a forward slash (/)
and must be less than 256 bytes in length. Please note that the length restriction applies to
the name after it has been URL encoded. For example, a container name of Course Docs
would be URL encoded as Course%20Docs and therefore be 13 bytes in length rather
than the expected 11.
You may create a container in either of our US data centers: ORD or DFW. However, in
order to lower your costs, you should create your most served containers in the same data
center as your server. Otherwise, you will be billed for external bandwidth charges.
2.5. Objects
Objects are the basic storage entities in Cloud Files. They represent the files and their
optional metadata you upload to the system. When you upload objects to Cloud Files,
the data is stored as-is (without compression or encryption) and consists of a location
(container), the object's name, and any metadata you assign consisting of key/value pairs.
For instance, you may choose to store a backup of your digital photos and organize them
into albums. In this case, each object could be tagged with metadata such as Album :
Caribbean Cruise or Album : Aspen Ski Trip.
The only restriction on object names is that they must be less than 1024 bytes in length
after URL encoding. For example, an object name of C++final(v2).txt should be URL
encoded as C%2B%2Bfinal%28v2%29.txt and therefore be 24 bytes in length rather
than the expected 16.
Cloud Files has a limit on the size of a single uploaded object; by default this is 5 GB.
However, the download size of a single object is virtually unlimited with the concept of
segmentation. Segments of the larger object are uploaded and a special manifest file is
created that, when downloaded, sends all the segments concatenated as a single object.
This also offers much greater upload speed with the possibility of parallel uploads of the
segments.
For metadata, you should not exceed 90 individual key/value pairs for any one object and
the total byte length of all key/value pairs should not exceed 4KB (4096 bytes).
2.6. Operations
Operations are the actions you perform within your account. Creating or deleting
containers, uploading or downloading objects, and so on. The full list of operations
is documented in the REST API sections Chapter 5, “API Operations for Storage
Services” [23] and Chapter 5, “API Operations for Storage Services” [23]. Operations
may be performed through the REST web service API or a language-specific API; currently,
we support Python, PHP, Java, Ruby, and C#/.NET.
Cloud Files™ Developer Guide
November 1, 2013
API v1
7
Important
All operations must include a valid authorization token.
2.7. CDN-Enabled Containers
To publish data that is to be served by a Content Distribution Network (CDN), containers
are publicly accessible and do not require an authentication token for read access.
Uploading content into a CDN-enabled container is a secure operation and requires a valid
authentication token.
Each CDN-enabled container has a unique Uniform Resource Locator (URL) that can be
combined with its object names and openly distributed in web pages, emails, or other
applications.
For example, a CDN-enabled container named photos might be referenced as
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com. If that container houses a screenshot called
wow1.jpg, then that image can be served by a CDN with the full URL of
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com/wow1.jpg.
This URL can be embedded in HTML pages, email messages, blog posts, and so on. When
that URL is accessed, a copy of that image is fetched from the Cloud Files storage system
and cached in a CDN and served from there for all subsequent requests for a configurable
cache time to live (TTL) value. Setting the TTL of a CDN-enabled container translates to
setting the Expires and Cache-Control HTTP headers. Cloud Files continues to serve
content through the CDN until it receives a delete request, although extremely long TTL
values do not guarantee that an object is served from a CDN edge location. When the TTL
expires, the CDN checks Cloud Files to ensure that it has the most up-to-date content. A
purge request forces the CDN to check with Cloud Files for the most up-to-date version of
the file.
Note
For more information about TTL, including its default, minimum, and maximum
values, see Section 6.3, “CDN Object Services” [66].
Containers tracked in the CDN management service are completely separate and distinct
from the containers defined in the storage service. It is possible for a container to be CDN-
enabled even if it does not exist in the storage system. Users may want the ability to pre-
generate CDN URLs before actually uploading content and this separation gives them that
ability.
However, for the content to be served from the CDN, the container names MUST match in
both the CDN management service and the storage service. For example, you could CDN-
enable a container called images and be assigned the CDN URL, but you also need to
create a container called images in the storage service.
Cloud Files™ Developer Guide
November 1, 2013
API v1
8
2.8. Language-Specific API Bindings
A set of API bindings in several popular languages are available to help put Cloud Files in
the hands of developers. These bindings provide a layer of abstraction on top of the base
REST API, allowing programmers to work with a container and object model instead of
working directly with HTTP requests and responses. The bindings are free (as in beer and
as in speech) to download, use, and modify. They are all licensed under the MIT License as
described in the COPYING file packaged with each binding. If you make any improvements
to an API, you are encouraged (but not required) to submit those changes back to us.
The API bindings are hosted at docs.rackspace.com/sdks/guide/content/intro.html.
If you have changes you would like to see in the Cloud Files bindings, email them to
cloudfiles@rackspacecloud.com. Make sure to indicate which language and version you
modified and send us a unified diff.
Each binding includes its own documentation (in HTML, PDF, or CHM format). They also
include code snippets and examples to help you get started. The API bindings for Cloud
Files are:
• PHP (requires 5.x and the modules: cURL, FileInfo, mbstring)
• Python (requires 2.4 or newer)
• Java (requires JRE v1.5 or newer)
There are no other language-specific bindings at this time. You are welcome to create your
own language API bindings and we will help answer any questions during development,
host your code if you like, and give you full credit for your work.
Cloud Files™ Developer Guide
November 1, 2013
API v1
9
3. General API Information
The information in this chapter is relevant to all Cloud Files API operations. See later
chapters for information about a specific API operation.
3.1. Authentication
Every REST request against the Cloud Files service requires the inclusion of a specific
authorization token, supplied by the X-Auth-Token HTTP header. Customers obtain
this token by first using the Rackspace Cloud Authentication Service and supplying a valid
username and API access key.
3.1.1. Geographic Endpoints
The Rackspace Cloud Authentication Service serves as the entry point to all Rackspace
Cloud APIs and is itself a RESTful web service.
To access the Authentication Service, you must know whether your account is US-based or
UK-based:
• US-based accounts authenticate through https://identity.api.rackspacecloud.com/v2.0/.
• UK-based accounts authenticate through https://lon.identity.api.rackspacecloud.com/
v2.0/.
Your account may be based in either the US or the UK; this is not determined by your
physical location but by the location of the Rackspace retail site which was used to create
your account:
• If your account was created via http://www.rackspacecloud.com, it is a US-based
account.
• If your account was created via http://www.rackspace.co.uk, it is a UK-based account.
If you are unsure how your account was created, use the Rackspace contact information at
either site to ask for help.
3.1.2. Retrieving the Authentication Token
POST
v2.0/tokens
Authenticate to receive a token and a service catalog.
Normal Response Code(s): 200, 203
Error Response Code(s): unauthorized (401), userDisabled (403), badRequest (400),
authFault (500), serviceUnavailable (503)
The authenticate operation provides clients with an authentication token and a list of
regional cloud endpoints. The sample requests and responses in this section illustrate
a general case. In your authentication request, use your own credentials rather than
the sample values shown here for username and apiKey. When you authenticate
successfully, the response to your authentication request will include a catalog of the
services to which you have subscribed rather than the sample values shown here.
Cloud Files™ Developer Guide
November 1, 2013
API v1
10
Example 3.1. Auth Request: XML
POST /v2.0/tokens HTTP/1.1
User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o
zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6
Host: identity.api.rackspacecloud.com
Accept: application/xml
Content-Type: application/xml
Content-Length: 88
<?xml version="1.0" encoding="UTF-8"?>
<auth>
<apiKeyCredentials
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
username=
"jsmith"
apiKey=
"aaaaa-bbbbb-ccccc-12345678"/>
</auth>

Example 3.2. Auth Request: JSON
POST /v2.0/tokens HTTP/1.1
User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o
zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6
Host: identity.api.rackspacecloud.com
Accept: application/json
Content-Type: application/json
Content-Length: 54
{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username":
"jsmith",
"apiKey":
"aaaaa-bbbbb-ccccc-12345678"
}
}
}

The username supplied here is your common Rackspace Cloud username.
The key is your API access key. The key can be obtained from the Rackspace Cloud
Control Panel in the <Your Account>/API Access section (login here: Control Panel
Login).
Example 3.3. Auth Response: XML
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:50:20 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Cloud Files™ Developer Guide
November 1, 2013
API v1
11
<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"/>
</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-eeeeeeee"

publicURL="https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
Cloud Files™ Developer Guide
November 1, 2013
API v1
12
internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
internalURL="https://snet-storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
</service>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
cccc-dddd-eeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-
cccc-dddd-eeeeeeee"/>
</service>
<service type="rax:dns" name="cloudDNS">
<endpoint tenantId="1100111"
publicURL="https://dns.api.rackspacecloud.com/v1.0/1100111"/>
</service>
</serviceCatalog>
</access>
Example 3.4. Auth Response: JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:45:13 GMT
{
"access": {


"token": {
"expires": "2011-12-08T22:51:02.000-06:00",
"id": "vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz"
},
"user": {
"id": "123456",
"name": "jsmith",
"RAX-AUTH:defaultRegion": "DFW",

"roles": [
{
"description": "Admin Role.",
"id": "identity:admin",
"name": "identity:admin"
},
{
"description": "Default Role.",
"id": "identity:default",
"name": "identity:default"
}
]
},

"serviceCatalog": [
{
"endpoints": [
Cloud Files™ Developer Guide
November 1, 2013
API v1
13
{
"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"
},
{
"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",
Cloud Files™ Developer Guide
November 1, 2013
API v1
14
"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-
eeeeeeee",

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

"region": "DFW"
},
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-
eeeeeeee",
"publicURL": "https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"internalURL": "https://snet-storage101.ord1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "ORD"
}
],

"name": "cloudFiles",

"type": "object-store"
},
{
"endpoints": [
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-
eeeeeeee",
"publicURL": "https://cdn1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "DFW"
},
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-
eeeeeeee",
"publicURL": "https://cdn2.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "ORD"
}
],
Cloud Files™ Developer Guide
November 1, 2013
API v1
15
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"tenantId": "1100111",
"publicURL": "https://dns.api.rackspacecloud.com/v1.0/
1100111"
}
],
"name": "cloudDNS",
"type": "rax:dns"
}
]
}
}

Note
The information shown in the Auth Response examples is for US-based
accounts. If you authenticate against the UK-endpoint for auth, you will see the
service catalog information for UK-based accounts.
In XML responses only, a list of namespaces identifies API extensions that add
functionality to the core API.
This token can be presented to a service as evidence of authentication. Tokens are
valid for a finite duration; a token's default lifespan is twenty-four hours.
The token's expires attribute denotes the time after which the token will
automatically become invalid. A token may be manually revoked before the time
identified by the expires attribute; expires predicts a token's maximum possible
lifespan but does not guarantee that it will reach that lifespan. Clients are encouraged
to cache a token until it expires.
Users can be assigned a default region so that, when there is a choice between
multiple endpoints associated with a service in the user's catalog, the endpoint for
the user's default region will be selected if it is available. In this example, the user's
default region is DFW and several of the services in the user's catalog offer endpoints
in that region and the ORD region; this user's work will be directed to the DFW region
whenever possible.
Users can be assigned multiple roles, with each role providing specific privileges.
In this example, jsmith is the administrative user for the account, holding the
fully-privileged identity:admin role. Other users might hold other roles with
different privileges. Roles need not be associated with actual job functions such as
Administrator, Operator, Developer, Tester, or Trainer.
The service catalog lists the services this user can access. In this example, the user
can access one database service, one loadbalancing service, two compute services
(Cloud Servers OpenStack and Cloud Servers), two object storage services (Cloud
Files Content Distribution Network (CDN), and Cloud Files), and one DNS service. The
Cloud Files™ Developer Guide
November 1, 2013
API v1
16
catalog listing for each service provides at least one endpoint URL for that service.
Other information, such as regions, versions, and tenants, is provided if it's relevant to
this user's access to this service.
The service type attribute identifies services that perform similar functions, whatever
those services might be named. In this example, the services named cloudServers and
cloudServersOpenstack are both identified as type="compute", identifying them as
compute services even though the word "compute" does not appear in their names.
Important
Use service type as the primary value for locating a service. If multiple
endpoints of the same service type exist in the same region, use service
name as the tiebreaker.
The service name attribute identifies each unique service in the catalog. Once a service
is created, its name does not change. However, new services of the same service type
may be added to the catalog with new names.
Important
If you are programmatically parsing an authentication response, use
service type rather than service name as the basis for determining whether
a user has access to a particular kind of service. Service type is stable across
all releases; new service types may be developed, but existing service types
are not renamed. In this example, type="compute" identifies all the
available compute services, one of which is named cloudServers and one of
which is named cloudServersOpenStack. New compute service names may
be added in future releases; whatever the compute services are named,
you can always recognize them by parsing for type="compute" in the
authentication response's service catalog.
A service may expose endpoints in different regions. Regional endpoints allow clients
to provision resources in a manner that provides high availability.
Some services are not region-specific. These services supply a single non-regional
endpoint and do not provide access to internal URLs.
Some services recognize specification of a tenant. If a service does recognize tenants,
the format of the tenant specification is defined only by the service; for details about
whether and how to specify a tenant, check the documentation for the service you are
using.
An endpoint can be assigned public and internal URLs. A public URL is accessible from
anywhere. Access to a public URL usually incurs traffic charges. Internal URLs are
only accessible to services within the same region. Access to an internal URL is free of
charge.
Authentication tokens are typically valid for 24 hours. Applications should be designed to
re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.
Cloud Files™ Developer Guide
November 1, 2013
API v1
17
Important
If you are programmatically parsing an authentication response, please be
aware that service names are stable for the life of the particular service and
can be used as keys. You should also be aware that a user's service catalog can
include multiple uniquely-named services which perform similar functions. For
example, cloudServersOpenStack is the OpenStack version of compute whereas
cloudServers is the legacy version of compute; the same user can have access
to both services. In Auth 2.0, the service type attribute can be used as a key by
which to recognize similar services; see the tip below.
Tip
Beginning with Auth 2.0, the service catalog includes a service type attribute
to identify services that perform similar functions but have different names; for
example, type="compute" identifies compute services such as cloudServers
and cloudServersOpenStack. Some developers have found the service type
attribute to be useful in parsing the service catalog. For additional information
on Auth 2.0 (also known as the Cloud Identity Service), refer to the Cloud
Identity Client Developer Guide at http://docs.rackspace.com/.
Cloud Files service endpoints are published in the service catalog in the Auth response
with the account number, which is a required element of the service endpoints. The
examples shown here are for authentication for US customers. Customers with UK-based
accounts will see different values in the service catalog. Refer to the next section for more
information about service endpoints.
Cloud Files™ Developer Guide
November 1, 2013
API v1
18
3.2. Role Based Access Control
Role Based Access Control (RBAC) restricts access to the capabilities of Rackspace Cloud
services, including the Cloud Files API, to authorized users only. RBAC enables Rackspace
Cloud customers to specify which account users of their Cloud account have access to which
Cloud Files API service capabilities, based on roles defined by Rackspace (see Table 3.1,
“Cloud Files Product Roles and Permissions” [18]). The permissions to perform certain
operations in the Cloud Files API – create, read, update, delete – are assigned to specific
roles, and these roles can be assigned by the Cloud account admin user to account users of
the account.
3.2.1. Assigning Roles to Account Users
The account owner (identity:user-admin) can create account users on the account and
then assign roles to those users. The roles grant the account users specific permissions for
accessing the capabilities of the Cloud Files service. Each account has only one account
owner, and that role is assigned by default to any Rackspace Cloud account when the
account is created.
See the Cloud Identity Client Developer Guide for information about how to perform the
following tasks:
• Create account users
• Assign roles to account users
• Delete roles from account users
Note
The account owner (identity:user-admin) role cannot hold any additional roles
because it already has full access to all capabilities.
3.2.2. Roles Available for Cloud Files
Two roles (admin and observer) can be used to access the Cloud Files API specifically. The
following table describes these roles and their permissions.
Table 3.1. Cloud Files Product Roles and Permissions
Role Name
Role Permissions
object-store:admin
This role provides Create, Read, Update, and Delete
permissions in Cloud Files, where access is granted.
object-store:observer
This role provides Read permission in Cloud Files, where
access is granted.
Additionally, two multiproduct roles apply to all products. Users with multiproduct
roles inherit access to future products when those products become RBAC-enabled. The
following table describes these roles and their permissions.
Cloud Files™ Developer Guide
November 1, 2013
API v1
19
Table 3.2.  Multiproduct (Global) Roles and Permissions
Role Name
Role Permissions
admin
This role provides Create, Read, Update, and Delete permissions in all
products, where access is granted.
observer
This role provides Read permission in all products, where access is granted.
3.2.3. Resolving Conflicts Between RBAC Multiproduct vs.
Custom (Product-specific) Roles
The account owner can set roles for both multiproduct and Cloud Files scope, and it is
important to understand how any potential conflicts among these roles are resolved. When
two roles appear to conflict, the role that provides the more extensive permissions takes
precedence. Therefore, admin roles take precedence over observer and creator roles,
because admin roles provide more permissions.
The following table shows two examples of how potential conflicts between user roles in
the Control Panel are resolved:
Permission Configuration
View of Permission
in the Control Panel
Can the User Perform Product Admin
Functions in the Control Panel?
User is assigned the following roles:
multiproduct observer and Cloud Files
admin
Appears that the user has only the
multiproduct observer role
Yes, for Cloud Files only. The user has
the observer role for the rest of the
products.
User is assigned the following roles:
multiproduct admin and Cloud Files
observer
Appears that the user has only the
multiproduct admin role
Yes, for all of the products. The Cloud
Files observer role is ignored.
3.2.4. RBAC Permissions Cross-reference to Cloud Files API
Operations
API operations for Cloud Files may or may not be available to all roles. To see which
operations are permitted to invoke which calls, please review the Knowledge Center
article.
3.3. Service Access Endpoints
Cloud Files is a regionalized service. The user of the service is therefore responsible for
appropriate replication, caching, and overall maintenance of Cloud Files data across
regional boundaries to other Cloud Files servers.
The endpoints to use for your Cloud Files API calls are summarized in the table below.
Table 3.3. Regionalized Service Endpoints
Region
Endpoint
https://storage101.ord1.clouddrive.com/v1/1234/
Chicago (ORD)
https://snet-storage101.ord1.clouddrive.com/v1/1234/
https://storage101.dfw1.clouddrive.com/v1/1234/
Dallas/Ft. Worth (DFW)
https://snet-storage101.dfw1.clouddrive.com/v1/1234/
Cloud Files™ Developer Guide
November 1, 2013
API v1
20
Region
Endpoint
https://storage101.hkg1.clouddrive.com/v1/1234/
Hong Kong (HKG)
https://snet-storage101.hkg1.clouddrive.com/v1/1234/
https://storage101.lon.clouddrive.com/v1/1234/
London (LON)
https://snet-storage101.lon.clouddrive.com/v1/1234/
https://storage101.iad3.clouddrive.com/v1/1234/
Northern Virginia (IAD)
https://snet-storage101.iad3.clouddrive.com/v1/1234/
https://storage101.syd2.clouddrive.com/v1/1234/
Sydney (SYD)
https://snet-storage101.syd2.clouddrive.com/v1/1234/
Replace the sample account ID number, 1234, with your actual account number returned
as part of the authentication service response.
You will find the actual account number after the final '/' in the publicURL field and the
internalURL field returned by the authentication response. For more information about
this account number, see sample authentication request and response in the Cloud Identity
Client Developer Guide.
Tip
If you do not know which data center you are working in or your account ID,
you can find them in your Cloud Control Panel at mycloud.rackspace.com.
If you are working with cloud servers that are in one of the Rackspace data centers, using
the ServiceNet endpoint in the same data center has no network costs and provides a faster
connection. ServiceNet endpoints are prefixed with snet- in Table 3.3, “Regionalized
Service Endpoints” [19]. ServiceNet is the data center internet network. In your
authentication response, it is listed as internalURL.
If you are working with servers that are not in one of the Rackspace data centers, you must
use a public endpoint to connect. In your authentication response, public endpoints are
listed as publicURL. If you are working with servers in multiple data centers or have a
mixed environment where you have servers in your data centers and in Rackspace data
centers, use a public endpoint because it is accessible from all the servers in the different
environments.
Cloud Files™ Developer Guide
November 1, 2013
API v1
21
4. Overview of API Operations
The Cloud Files API is implemented as a set of RESTful web services. All authentication and
container/object operations can be performed with standard HTTP calls. See the Wikipedia
article on REST for more information.
The following constraints apply to the REST API's 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 should be properly URL-encoded prior to interacting with the
REST interface (the language APIs handle URL encoding/decoding) and the container and
object names must be UTF-8 encoded. The length restrictions should be checked against the
URL-encoded string.
Each REST request against the Cloud Files system requires the inclusion of a specific
authorization token HTTP header defined as X-Auth-Token. Clients obtain this token,
along with the Cloud Files URLs, by first using the Authentication service and supplying a
valid Username and API Access Key.
There are actually two different sets of REST services that make up the full Cloud Files
product. The first REST service identified with cloudFiles in the service catalog
(see Example 5.18, “Example of Multi-region Data Center Endpoints from the Service
Catalog” [30]) is used for managing the data stored in the system. Example operations
are creating containers and uploading objects. The second REST service is for managing the
CDN feature of Cloud Files and is identified by cloudFilesCDN in the service catalog.
In the following sections, the purpose of each HTTP method depends upon which service
the call is made against. For example, a PUT request against one of the cloudFiles
endpoints can be used to create a container or upload an object, while a PUT request
against the one of the cloufFilesCDN endpoints is used to CDN-enable a container.
The language-specific APIs mask this system separation from the programmer. They simply
create a container and mark it public and it handles calling out to the appropriate back-end
services using the appropriate REST API.
Note
All requests to authenticate and operate against Cloud Files are performed
using SSL over HTTP (HTTPS) on TCP port 443.
Cloud Files™ Developer Guide
November 1, 2013
API v1
22
The following diagram illustrates the various system interfaces and the ease with which
content can be distributed over the CDN. The process is simple: authenticate, create a
container, upload objects, mark the container as public, and begin serving that content
from a powerful CDN.
Figure 4.1. Cloud Files System Interfaces
Cloud Files™ Developer Guide
November 1, 2013
API v1
23
5. API Operations for Storage Services
The following section describes the REST API for interacting with the storage component
of Cloud Files. All requests will be directed to the host and endpoings described in the
cloudFiles obtained during successful authentication.
The following are some requirements for the use of the storage services:
• 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.
• Object and container names must be URL-encoded and UTF-8 encoded.
The following sections describe the actions that may be performed within the storage
system. The first section addresses actions that can be taken on the account level of
the storage system. The second section addresses actions that may be performed on
containers. The third section addresses actions that may be performed on objects.
5.1. Storage Account Services
The following operations can be performed at the account level of the URL. For example,
the URL for the requests below will end with the Cloud Files account string:
Example 5.1. Storage Account HTTP Request: General Structure
METHOD /v1/<account> HTTP/1.1

This section shows how to view and control the display of your Cloud Files account details.
You may use the below optional parameters to help control the amount of information
displayed.
Query Parameters
limit For an integer value n, limits the number of results to n values.
marker Given a string value x, return container names greater in value than the
specified marker. Only strings using UTF-8 encoding are valid.
end_marker Given a string value x, return container names lower in value than the
specified end marker. Only strings using UTF-8 encoding are valid.
format Specify either json or xml to return the respective serialized response.
At this time, a prefix query parameter is not supported at the account level.
5.1.1. View Account Details
To see how many containers you have in your account (X-Account-Container-Count),
how many objects are in your account (X-Account-Object-Count), and how many
Cloud Files™ Developer Guide
November 1, 2013
API v1
24
total bytes your account uses (X-Account-Bytes-Used), do a HEAD request against
your storage account URL. This displays your Account Information. A 204 (No Content)
code returns and there is no information in the response body.
The examples in this section use a sample auth account, listed in X-Auth-Token. When
you do your own requests, you must use your own auth token. You can check how to
generate this token in Section 3.1: “Authentication”.
Example 5.2. View Account Information Request
HEAD /<api version>/<account> HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

Example 5.3. View Account Information Response
HTTP/1.1 204 No Content
Content-Type: text/html; charset=UTF-8
X-Account-Object-Count: 12
X-Trans-Id: txc44b00fccb6a49318626d3cac1d2cdb6
Date: Tue, 06 Nov 2012 19:50:04 GMT
X-Account-Bytes-Used: 10373619
Content-Length: 0
X-Account-Container-Count: 5

5.1.2. List Containers
The container is the basic storage unit in Cloud Files. To view a list of the containers in your
account, do a GET request against your storage account URL. The list is limited to 10,000
containers at a time. See the below section, Section 5.1.2.2: “Controlling a Large List of
Containers”, for information on limiting and navigating the list. A 200 (OK) code returns if
there are containers and a 204 (No Content) code returns if there are no containers.
Container names are sorted based on a binary comparison, a single built-in collating
sequence that compares string data using SQLite's memcmp() function, regardless of text
encoding.
Example 5.4. View Containers List Request
GET /<api version>/<account> HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

Example 5.5. View Containers List Response
HTTP/1.1 200 OK
Date: Thu, 07 Jun 2007 18:57:07 GMT
Cloud Files™ Developer Guide
November 1, 2013
API v1
25
Content-Type: text/plain; charset=UTF-8
Content-Length: 32

images
movies
documents
backups

5.1.2.1. Format Container List
If a format=xml or format=json argument is appended to the storage account URL,
the service will serve extended container information serialized in the chosen format.
If you format your results, the formatting parameter must be written before any other
parameters. The sample responses below are formatted for readability.
Example 5.6. Container Details Request: JSON
GET /<api version>/<account>?format=json HTTP/1.1
Host: storage.clouddrive.com
Content-Length: 0
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example 5.7. Container Details Response: JSON
HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:39:13 GMT
Content-Type: application/json; charset=utf-8

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

Example 5.8. Container Details Request: XML
GET /<api version>/<account>?format=xml HTTP/1.1
Host: storage.clouddrive.com
Content-Length: 0
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example 5.9. Container Details Response: XML
HTTP/1.1 200 OK
Date: Tue, 25 Nov 2008 19:42:35 GMT
Content-Type: application/xml; charset=utf-8
Cloud Files™ Developer Guide
November 1, 2013
API v1
26

<?xml version="1.0" encoding="UTF-8"?>
<account name="MichaelBarton">
<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>

5.1.2.2. Controlling a Large List of Containers
A GET request to the storage account URL returns a list of up to 10,000 container names.
You may limit and control this list of results by using the marker and end_marker
parameters.
Marker tells Cloud Files where to begin your list of containers and end_marker notes
where to end the list. You may use either of them independently, or together, separated by
an &. If you use them on their own, your list will display up to 10,000 containers. Note that
the marker and end_marker values should be URL-encoded prior to sending the HTTP
request.
You may also use the limit parameter to lower the number of returned objects.
Example 5.10. List Large Number of Containers
For example, use a listing of five container names:
apples
bananas
kiwis
oranges
pears

Use a limit of two to show how things work:
GET /<api version>/<account>?limit=2
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

apples
bananas

Cloud Files™ Developer Guide
November 1, 2013
API v1
27
Since we received two items back, we can assume there are more container names to list,
so we make another request with a marker of the last item returned:
GET /<api version>/<account>?limit=2&marker=bananas
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

kiwis
oranges

Again, two items are returned; there may be more:
GET /<api version>/<account>?limit=2&marker=oranges
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

pears

With this one-item response, we received less than the limit number of container names,
which indicates that this is the end of the list.
5.2. Storage Container Services
This section documents the REST operations that can be performed on containers. All
operations are valid HTTP request methods and will resemble this format:
Example 5.11. Storage Container HTTP Request: General Structure
METHOD /v1/<account>/<container> HTTP/1.1

This section shows how to view and control the details information for containers in your
Cloud Files account. You may use the below optional parameters to help control the
amount of information displayed.
Query Parameters
limit For an integer value n, limits the number of results to n values.
marker Given a string value x, return object names greater in value than the
specified marker. Only strings using UTF-8 encoding are valid.
end_marker Given a string value x, return object names lower in value than the
specified end marker. Only strings using UTF-8 encoding are valid.
prefix For a string value x, causes the results to be limited to object names
beginning with the substring x.
Cloud Files™ Developer Guide
November 1, 2013
API v1
28
format Specify either json or xml to return the respective serialized response.
delimiter For a character c, return all the object names nested in the container.
5.2.1. View Container Details
To see how many objects are in a container (X-Container-Object-Count) and the
custom metadata you have set on the container (X-Container-Meta-TraitX), do a
HEAD request against the container's URL. To set and edit your custom metadata, see
Section 5.2.4: “Set or Edit Container Metadata”. A 204 (No Content) code returns and there
is no information in the response body.
Example 5.12. View Container Details Request
HEAD /v1/MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c/MobyDick?
format=json
Accept-Encoding: gzip
x-Auth-Token: be221903-f12a-469f-b16c-48106ff22ebe

Example 5.13. View Container Details Response
HTTP/1.1 204 No Content
Connection: keep-alive
Content-Type: text/html; charset=UTF-8
X-Container-Object-Count: 5
X-Trans-Id: tx30e27bcc8bf34c0ebfdf078337895478
X-Timestamp: 1331584412.96818
X-Container-Meta-Book: MobyDick
Accept-Ranges: bytes
Date: Thu, 08 Nov 2012 19:08:25 GMT
X-Container-Meta-Subject: Whaling
Content-Length: 0
X-Container-Bytes-Used: 3846773

5.2.2. Create Container
PUT operations against a storage container are used to create that container. You may
create up to 500,000 containers in your Cloud Files account.
Containers are storage compartments for your data. The URL encoded name must be less
than 256 bytes and cannot contain a forward slash '/' character.
Containers can be assigned custom metadata by including additional HTTP headers on
the PUT request. The custom metadata is assigned to a container through HTTP headers
identified with the X-Container-Meta-XXXX prefix. See Section 6.2.4: “Update CDN-
Enabled Container Metadata” for details on setting custom metadata.
Example 5.14. Container Create Request
Cloud Files™ Developer Guide
November 1, 2013
API v1
29
PUT /<api version>/<account>/<container> HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

No content is returned. 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 when the container already existed. If you request a PUT to a
container with an X-Container-Meta- prefix in the header, your GET/HEAD request