Rackspace Cloud Filesâ¢ Developer Guide

Transcription

docs.rackspace.com/api
Rackspace Cloud Files™ Developer Guide
May 1, 2015
API v1
API v1 (2015-05-01)
©2015 Rackspace US, Inc.
This document is intended for software developers interested in developing applications using the Rackspace Cloud Files™ Application
Programming Interface (API). The document is for informational purposes only and is provided “AS IS.”
RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND PRODUCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE WITHOUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT AS SET
FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO LIABILITY
WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any
license to patents, trademarks, copyrights, or other intellectual property.
Rackspace®, Rackspace logo and Fanatical Support® are registered service marks of Rackspace US, Inc. All other product names and
trademarks used in this document are for identification purposes only and are property of their respective owners.
ii
May 1, 2015
API v1
Table of Contents
1. Overview ..................................................................................................................... 1
1.1. Intended audience ........................................................................................... 1
1.2. Document change history ................................................................................. 2
1.3. Additional resources ......................................................................................... 5
1.4. Pricing and service level .................................................................................... 6
2. Concepts ..................................................................................................................... 7
2.1. Accounts .......................................................................................................... 7
2.2. Authentication ................................................................................................. 7
2.3. Permissions ....................................................................................................... 7
2.4. Containers ........................................................................................................ 7
2.5. Objects ............................................................................................................. 8
2.6. Operations ....................................................................................................... 8
2.7. CDN-enabled containers ................................................................................... 9
2.8. Language-specific APIs .................................................................................... 10
3. General API information ............................................................................................ 11
3.1. Authentication ............................................................................................... 11
3.1.1. Geographic endpoints .......................................................................... 11
3.1.2. Retrieving the authentication token ..................................................... 11
3.2. Role Based Access Control .............................................................................. 21
3.2.1. Assigning roles to account users ........................................................... 21
3.2.2. Roles available for Cloud Files .............................................................. 21
3.2.3. Resolving conflicts between RBAC multiproduct and custom (product-specific) roles ........................................................................................... 22
3.2.4. RBAC permissions cross-reference to Cloud Files API operations ............. 22
3.3. Service access endpoints ................................................................................. 22
3.4. Cloud Files service contract version ................................................................. 25
3.5. Absolute limits ................................................................................................ 25
3.6. Request and response types ........................................................................... 26
3.7. Response codes .............................................................................................. 26
4. Overview of API operations ....................................................................................... 28
5. API operations for storage services ............................................................................ 30
5.1. Account services ............................................................................................. 31
5.1.1. Show account details and list containers ............................................... 32
5.1.2. Create or update account metadata .................................................... 38
5.1.3. Get account metadata ......................................................................... 40
5.1.4. Delete account metadata ..................................................................... 42
5.2. Container services ........................................................................................... 43
5.2.1. Show container details and list objects ................................................. 45
5.2.2. Create container .................................................................................. 50
5.2.3. Delete container .................................................................................. 53
5.2.4. Create or update container metadata .................................................. 55
5.2.5. Show container metadata .................................................................... 58
5.2.6. Delete container metadata .................................................................. 61
5.3. Object services ................................................................................................ 62
5.3.1. Get object content and metadata ........................................................ 64
5.3.2. Create or update object ....................................................................... 68
5.3.3. Delete object ....................................................................................... 72
5.3.4. Copy object ......................................................................................... 74
iii
May 1, 2015
API v1
5.3.5. Show object metadata ......................................................................... 79
5.3.6. Create or update object metadata ....................................................... 82
6. Pseudo hierarchical folders and directories ................................................................. 85
7. Additional container services information .................................................................. 87
7.1. Container access control lists .......................................................................... 87
7.2. Container quotas ............................................................................................ 88
7.3. Access log delivery .......................................................................................... 89
8. Additional object services information ....................................................................... 91
8.1. Chunked transfer encoding ............................................................................. 91
8.2. Creating large objects ..................................................................................... 91
8.2.1. Creating a dynamic large object ........................................................... 93
8.2.2. Creating a static large object ............................................................... 95
8.3. Enabling file compression ............................................................................... 99
8.4. Enabling bypass of browser behavior .............................................................. 99
8.5. Expiring objects ............................................................................................ 100
8.6. Object versioning .......................................................................................... 100
8.7. Account to account copy .............................................................................. 102
9. API operations for CDN services ............................................................................... 105
9.1. CDN account services .................................................................................... 105
9.1.1. List CDN-enabled containers ............................................................... 107
9.2. CDN container services ................................................................................. 108
9.2.1. CDN-enable and CDN-disable a container ........................................... 110
9.2.2. List metadata for CDN-enabled container ........................................... 113
9.2.3. Update CDN-enabled container metadata .......................................... 116
9.3. CDN object services ...................................................................................... 117
9.3.1. Delete CDN-enabled object ................................................................ 118
10. Additional CDN services information ...................................................................... 121
10.1. Purge CDN-enabled containers .................................................................... 121
10.2. CDN-enabled containers served through SSL ................................................ 121
10.3. Streaming CDN-enabled containers ............................................................. 121
10.4. iOS streaming ............................................................................................. 122
10.5. CDN log delivery ......................................................................................... 123
11. Static websites using CDN-enabled containers ........................................................ 126
11.1. Create a static website ................................................................................ 126
11.2. Set error pages for a static website ............................................................. 128
12. Bulk operations ..................................................................................................... 129
12.1. Extracting archive files ................................................................................ 129
12.2. Bulk delete ................................................................................................. 131
13. Public access to your Cloud Files account ................................................................ 134
13.1. TempURL .................................................................................................... 134
13.1.1. Set account TempURL metadata key ................................................ 134
13.1.2. Create the TempURL ........................................................................ 135
13.1.3. Override TempURL file names .......................................................... 136
13.2. FormPost .................................................................................................... 137
13.2.1. Set account metadata key ................................................................ 137
13.2.2. Create the form ............................................................................... 138
13.3. CORS .......................................................................................................... 140
13.3.1. CORS headers for containers ............................................................ 140
13.3.2. CORS headers for objects ................................................................. 143
Glossary ....................................................................................................................... 145
iv
May 1, 2015
API v1
List of Figures
4.1. Cloud Files system interfaces ................................................................................... 29
v
May 1, 2015
API v1
List of Tables
3.1. Cloud Files product roles and permissions ............................................................... 21
3.2. Multiproduct (global) roles and permissions ............................................................ 22
3.3. Regionalized service endpoints for storage services ................................................. 23
3.4. Regionalized service endpoints for CDN management services ................................. 24
3.5. Absolute limits ........................................................................................................ 25
5.1. Cloud Files supported range formats ...................................................................... 64
7.1. Metadata values for setting container quotas ......................................................... 89
8.1. Comparison of static and dynamic large objects ...................................................... 93
13.1. CORS container-level headers .............................................................................. 141
13.2. CORS object-level headers ................................................................................... 143
vi
May 1, 2015
API v1
List of Examples
3.1. Authentication request: XML ..................................................................................
3.2. Authentication request: JSON .................................................................................
3.3. Authentication response: XML ................................................................................
3.4. Authentication response: JSON ...............................................................................
3.5. Example request URL (contract version in bold) ......................................................
3.6. Error message example ...........................................................................................
5.1. Show account details and list containers: XML request ............................................
5.2. Show account details and list containers: JSON request ...........................................
5.3. Show account details and list containers: XML response ..........................................
5.4. Show account details and list containers: JSON response .........................................
5.5. Create or update account metadata: HTTP request .................................................
5.6. Create or update account metadata: HTTP response ...............................................
5.7. Get account metadata: HTTP request .....................................................................
5.8. Get account metadata: HTTP response ...................................................................
5.9. Delete account metadata: HTTP request .................................................................
5.10. Delete account metadata: HTTP response .............................................................
5.11. Show container details and list objects: XML request .............................................
5.12. Show container details and list objects: JSON request ............................................
5.13. Show container details and list objects: XML response ...........................................
5.14. Show container details and list objects: JSON response ..........................................
5.15. Create container: HTTP request ............................................................................
5.16. Create container with metadata: HTTP request .....................................................
5.17. Create container: HTTP response ..........................................................................
5.18. Create container with metadata: HTTP response ...................................................
5.19. Delete container: HTTP request .............................................................................
5.20. Delete container: HTTP response ..........................................................................
5.21. Create or update container metadata: HTTP request .............................................
5.22. Create or update container metadata: HTTP response ...........................................
5.23. Get container metadata: HTTP request .................................................................
5.24. Get container metadata: HTTP response ...............................................................
5.25. Delete container metadata: HTTP request .............................................................
5.26. Delete container metadata: HTTP response ...........................................................
5.27. Get object data: HTTP request ..............................................................................
5.28. Get object data using a range: HTTP request ........................................................
5.29. Get object data using multiple ranges: HTTP request .............................................
5.30. Get object data response ......................................................................................
5.31. Get object data using range response ...................................................................
5.32. Get object data using multiple ranges response ....................................................
5.33. Create or update object request ...........................................................................
5.34. Create or update object: HTTP response ...............................................................
5.35. Delete object: HTTP request .................................................................................
5.36. Delete object: HTTP response ...............................................................................
5.37. Copy object approach 1 - using COPY ...................................................................
5.38. Copy object approach 2 - using PUT ......................................................................
5.39. Data center endpoints ..........................................................................................
5.40. Copy object using COPY: HTTP request .................................................................
5.41. Copy object using PUT: HTTP request ....................................................................
5.42. Copy object using COPY: HTTP response ...............................................................
vii
12
12
13
15
25
27
34
35
36
36
39
39
40
41
42
43
47
47
48
49
51
51
51
52
53
54
57
57
58
59
62
62
65
65
66
67
67
67
70
71
73
73
74
74
75
76
77
77
May 1, 2015
API v1
5.43. Copy object using PUT: HTTP response .................................................................. 77
5.44. Get object metadata: HTTP request ...................................................................... 80
5.45. Get object metadata: HTTP response .................................................................... 81
5.46. Update object metadata: HTTP request ................................................................ 83
5.47. Update object metadata: HTTP response .............................................................. 84
7.1. Show container metadata before adding ACL headers: HTTP request ...................... 87
7.2. Show container metadata before adding ACL headers: HTTP response .................... 88
7.3. Update container to add ACL headers: HTTP request .............................................. 88
7.4. Show container metadata after adding ACL headers: HTTP request ......................... 88
7.5. Show container metadata after adding ACL headers: HTTP response ....................... 88
7.6. Example access log entries ...................................................................................... 90
8.1. Upload unspecified quantity of data: HTTP request ................................................. 91
8.2. Upload unspecified quantity of data response ........................................................ 91
8.3. Upload a segment of a large object: HTTP request .................................................. 94
8.4. Upload a segment of a large object response ......................................................... 94
8.5. Upload the next segment of the large object : HTTP request ................................... 95
8.6. Upload the next segment of the large object response ............................................ 95
8.7. Upload manifest: HTTP request .............................................................................. 95
8.8. Upload manifest response ...................................................................................... 95
8.9. Static large object manifest list ............................................................................... 97
8.10. Content-Encoding: HTTP request ........................................................................... 99
8.11. Content-Disposition: HTTP request ........................................................................ 99
8.12. X-Delete-At: HTTP request ................................................................................... 100
8.13. X-Delete-After: HTTP request .............................................................................. 100
8.14. Object versioning with cURL ............................................................................... 102
9.1. List CDN-enabled containers: HTTP request ........................................................... 107
9.2. List CDN-enabled containers: HTTP request with a query parameter ?format=json
..................................................................................................................................... 108
9.3. List CDN-enabled containers: HTTP response ......................................................... 108
9.4. List CDN-enabled containers: HTTP response using a query parameter ?
format=json ................................................................................................................. 108
9.5. CDN-enable container: HTTP request ..................................................................... 111
9.6. CDN-disable container: HTTP request .................................................................... 111
9.7. CDN-enable container: HTTP response ................................................................... 112
9.8. List metadata for CDN-enabled container: HTTP request ........................................ 114
9.9. List metadata for CDN-enabled container: JSON request ........................................ 114
9.10. List metadata for CDN-enabled container: XML request ....................................... 114
9.11. Get CDN-enabled container metadata: HTTP request ........................................... 114
9.12. List metadata for CDN-enabled container: JSON response .................................... 115
9.13. List metadata for CDN-enabled container: XML response ..................................... 115
9.14. Update CDN-enabled container metadata: HTTP request ..................................... 116
9.15. Update CDN-enabled container metadata: HTTP response ................................... 117
9.16. Delete CDN-enabled object: HTTP request ........................................................... 119
9.17. Delete CDN-enabled object: HTTP response ......................................................... 119
10.1. CDN-enabled container metadata: HTTP request ................................................. 121
10.2. CDN-enabled container metadata with SSL URI: HTTP response ........................... 121
10.3. CDN-enabled container metadata: HTTP request ................................................. 122
10.4. CDN-enabled container metadata with streaming URIs: HTTP response ................ 122
10.5. HTML 5 video element ........................................................................................ 123
10.6. JavaScript for user agent check ........................................................................... 123
10.7. Load JavaScript in HTML page ............................................................................ 123
viii
May 1, 2015
API v1
10.8. Example CDN log entries ....................................................................................
11.1. Set up static web ................................................................................................
11.2. Container setup for static website .......................................................................
11.3. Static website enabled container results ..............................................................
11.4. Set error pages for static website: HTTP request ..................................................
12.1. Example extract archive request ..........................................................................
12.2. Successful extract archive response .....................................................................
12.3. Extract archive response with errors ....................................................................
12.4. Create text file for bulk delete request ................................................................
12.5. cURL request for the bulk delete ........................................................................
12.6. HTTP request for the bulk delete ........................................................................
12.7. Successful bulk delete response ...........................................................................
12.8. Bulk delete response with errors .........................................................................
13.1. Set account metadata key for public access: HTTP request ...................................
13.2. Create TempURL (in Python) ...............................................................................
13.3. Create TempURL (in PHP) ...................................................................................
13.4. Create TempURL (in Ruby) ..................................................................................
13.5. TempURL without file name override ..................................................................
13.6. TempURL with file name override - Example 1 .....................................................
13.7. TempURL with file name override - Example 2 .....................................................
13.8. TempURL with inline query parameter ................................................................
13.9. Set account metadata key for public access: HTTP request ...................................
13.10. Layout of web form ..........................................................................................
13.11. Generate signature for FormPost ......................................................................
13.12. Example of a CORS POST cURL request .............................................................
13.13. Test CORS page ................................................................................................
13.14. Assign CORS header request for an object .........................................................
ix
124
127
127
127
128
129
130
130
131
132
132
132
132
135
135
136
136
136
137
137
137
138
138
139
142
142
144
May 1, 2015
API v1
1. Overview
Rackspace Cloud Files™ is an affordable, redundant, scalable, and dynamic storage service.
The core storage system is designed to provide a secure, network-accessible way to store an
unlimited number of files. Each file can be as large as 5 gigabytes. You can store as much as
you want and pay only for storage space that you actually use.
Cloud Files also provides a simple yet powerful way to publish and distribute content behind a content delivery network (CDN). As a Cloud Files user, you get access to this network
automatically.
Cloud Files enables you to store and retrieve files and CDN-enabled content through
a RESTful (Representational State Transfer) web services interface. There are also language-specific application programming interfaces (APIs) that use the RESTful API and
make it easy for developers to integrate into their applications.
For more details about the Cloud Files service, see http://www.rackspace.com/cloud/files/
and the Knowledge Center article Best Practices for Using Cloud Files.
Rackspace welcomes feedback, comments, and bug reports at
[email protected].
1.1. Intended audience
This guide is intended to assist software developers who want to develop applications using the Rackspace Cloud Files API. It fully documents the REST application programming interface (API) that allows developers to interact with the storage and CDN components of
the Cloud Files system. To use the information provided here, you must 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 the following items:
• RESTful web services
• HTTP/1.1
System administrators and others interested in the storage and CDN benefits of Cloud Files
should consider using the File Manager interface within the Rackspace Cloud Control Panel, Jungle Disk, or third-party tools such as Fileuploader or Cyberduck. The Rackspace Cloud
Control Panel provides an easy to use web-based interface for uploading content to and
downloading content from Cloud Files.
Rackspace also provides language-specific APIs in several popular programming languages.
Customers who are interested in accessing Cloud Files by using one of the language-specific APIs should see the Rackspace Cloud SDKs Software Development Kit Guide. For information about language-specific APIs, see Language-Specific API Bindings.
1
May 1, 2015
API v1
1.2. Document change history
This version of the Developer Guide replaces and obsoletes all earlier versions. The most recent changes are described in the following table:
Revision Date
Summary of Changes
May 1, 2015
• Updated Create or update object metadata to remove the sentence "You cannot use this
operation to change other headers, such as Content-Type." as this statement is not true. You
can update header information with this operation.
April 23, 2015
• Corrected links in Assigning roles to account users.
March 23, 2015
• Corrected the URI in the table in Section 9.3, “CDN object services” [117] to include the
container information and added a warning with information to make sure that you are using the CDN management services URIs for this DELETE operation.
• Corrected the URI in Delete CDN-enabled object to include the container information and
added additional information to this operation description with updated request and response examples.
March 4, 2015
Removed the London endpoint for the Rackspace Cloud Identity service. Rackspace now has
one global endpoint for authentication. See Section 3.1, “Authentication” [11].
February 26, 2015
• Added the account to account copy capability described in Section 8.7, “Account to account
copy” [102].
• Added the Destination-Account header, which is used to make an account to account
copy, to the COPY command request parameters in Copy object.
• Added the X-Copy-From-Account header, which is used to make an account to account
copy, to the PUT command request parameters in Create or update object.
January 14, 2015
Updated Section 3.1.2, “Retrieving the authentication token” [11] with information about
using multi-factor authentication for added security when a user authenticates with username and password credentials.
January 7, 2015
Removed the section "Bulk importing of data". Starting January 1, 2015, this service is not available.
December 17, 2014
In the description for the operation to CDN-enable and CDN-disable a container at "CDN-enable and CDN-disable a container", corrected the X-Cdn-Uri response parameter type to
string and noted that this response parameter is required.
December 3, 2014
Updated the table in Section 3.5, “Absolute limits” [25] for the rate limit for write operations to read "100 write operations per second per container" rather than "100 operations per
second".
November 11, 2014
Updated Section 13.1.1, “Set account TempURL metadata key” [134] by adding information about changing X-Account-Meta-Temp-Url-Key and the use of a second key, X-Account-Meta-Temp-Url-Key-2.
September 5, 2014
• Updated Section 13.3, “CORS ” [140]. This section now includes the following subsections
to describe the available access control headers:
• Section 13.3.1, “CORS headers for containers” [140]
• Section 13.3.2, “CORS headers for objects” [143]
• Added a note to Section 11.1, “Create a static website” [126] about how to disable a static website that you have created.
August 28, 2014
• Added an example request to Section 12.1, “Extracting archive files” [129].
• Updated Section 13.2, “FormPost” [137] by adding the following information:
• Additional information about the max_file_count parameter
• A description for the x-delete-at and x-delete-after parameters
These parameters allow you to set the expiration for an object that is uploaded using
FormPost.
2
May 1, 2015
Revision Date
API v1
Summary of Changes
• Corrected the link to service access endpoint information in "List CDN-enabled containers".
July 25, 2014
Corrected an error in the Python example to create a TempURL in Section 13.1.2, “Create the
TempURL” [135]. (Removed AMP from the last print in the example.)
July 22, 2014
Added a link to guidance on choosing a regionalized endpoint in Section 3.3, “Service access
endpoints” [22].
July 18, 2014
• Changed the format for CDN logs from storing the month as 3 letters to using the following
format: DD/MM/YYYY (for example, 16/07/2014).
• Added Section 10.5, “CDN log delivery” [123].
April 30, 2014
• Updated the TTL maximum value to 1 year (31536000 seconds) instead of 50 years
(1577836800 seconds) throughout Chapter 9, “API operations for CDN services” [105].
• Removed Chapter 14, "Examples using cURL". This information is now included with other
cURL examples in the new Cloud Files Getting Started Guide.
April 7, 2014
• Added Section 7.1, “Container access control lists” [87].
April 1, 2014
• Added header descriptions to the operations in Chapter 5, “API operations for storage services” [30].
• Updated the "Bulk importing of data"section to show the availability of using this feature in
Sydney.
February 21, 2014
• Updated the table in Section 3.5, “Absolute limits” [25] to include the rate limit for write
operations, which is 100 operations per second per container.
• Updated the following object methods to include the X-Detect-Content-Type header
in the request:
• PUT (Create or update object)
• POST (Update object metadata)
• COPY (Copy object)
If you set this header to True, the Content-Type that is sent in the request (if any) is ignored, and Content-Type is guessed by using the Python mimetypes library based on the
object path.
• Reworked Chapter 5, “API operations for storage services” [30] and Chapter 9, “API operations for CDN services” [105] 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” [11].
• Added a table that lists and briefly describes all API operations. Also added tables showing
the API operations at the beginning of each section that describes the operations.
• Added service access endpoints for the CDN management service component to Section 3.3,
“Service access endpoints” [22].
• Updated account information in Section 3.3, “Service access endpoints” [22] to show
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee rather than 1234.
• Added Section 3.4, “Cloud Files service contract version” [25].
• Added Section 3.5, “Absolute limits” [25].
• Added Section 3.6, “Request and response types” [26].
• Added the section for the operation to create or update account metadata in Chapter 5,
“API operations for storage services” [30].
• Added the section for the operation to delete account metadata in Chapter 5, “API operations for storage services” [30].
3
May 1, 2015
Revision Date
API v1
Summary of Changes
• In all examples, updated the X-Auth-Token header to use the current format returned by
an authentication request (no dashes). Also updated examples to use real values for account, container, and object.
November 26, 2013
• Added Section 8.2, “Creating large objects” [91] with more information about dynamic
large objects and static large objects.
• Updated Section 12.1, “Extracting archive files” [129] to include a note about using a
blank Content-Type header to have Cloud Files determine the file type for the archive.
November 22, 2013
• Added service catalog information for cloudfilesCDN endpoints (Section 3.3, “Service access endpoints” [22]).
• Made miscellaneous updates throughout this book to improve wording and consistency.
November 1, 2013
• Replaced references to X-Storage-Url and X-Cdn-Management–Url throughout this
document with references to the cloudFiles and cloudFilesCDN endpoints in the service catalog based on use of Identity v2.0 rather than Identity v1.0.
• Updated Section 2.2, “Authentication” [7] to include new references to additional information about the service access endpoints and the service catalog.
• Updated authentication requests to use Identity v2.0.
October 25, 2013
• Added Section 3.3, “Service access endpoints” [22], which includes all endpoints for
Cloud Files including the newest one in Hong Kong.
• Updated Section 3.1, “Authentication” [11] to show information for Rackspace Identity
v2.0.
• Updated Section 13.2.2, “Create the form” [138] to indicate that the value of the redirect parameter can be empty to indicate that no redirect is included on the form.
September 26, 2013
• Added Section 3.2, “Role Based Access Control” [21].
• Updated Section 13.3, “CORS ” [140].
September 19, 2013
• Updated responses to show application/json in Section 12.2, “Bulk delete” [131].
• Added the X-Container-Meta-Web-Listings, X-Container-Meta-Web-Listings-Css, and X-Container-Meta-Web-Directory-Type headers to Section 11.1,
“Create a static website” [126].
July 18, 2013
• Clarified information about the redirect and expires parameters in Section 13.2.2, “Create the form” [138].
June 27, 2013
• Changed references for authentication to point to Cloud Identity v2.0.
• In Section 9.3, “CDN object services” [117] in the section for the operation to delete a
CDN-enabled object, added a note about removing a CDN-enabled container by setting XCdn-Enabled to False in the HEAD operation.
June 14, 2013
• Added information about authentication, v1 and v2, in Section 3.1, “Authentication” [11].
May 20, 2013
• Added a link in Chapter 1, “Overview” [1] to the Knowledge Center article, "Best Practices
for Using Cloud Files," at http://www.rackspace.com/knowledge_center/article/best-practices-for-using-cloud-files.
• Added Section 7.2, “Container quotas” [88].
• Created a new section Section 5.3, “Object services” [62]. This section includes new and
previously existing information specifically related to storage objects.
• Added Section 8.2.2, “Creating a static large object” [95].
• Added Chapter 12, “Bulk operations ” [129].
• Added Section 13.1.3, “Override TempURL file names” [136].
February 1, 2013
• Changed the location of SDKs. Added a note about object metadata behavior.
December 5, 2012
• Added Section 10.4, “iOS streaming” [122].
November 30, 2012
• Fixed internal linking.
November 16, 2012
• Added the end_marker list parameter and CORS container headers.
October 31, 2012
Updated language binding language and links.
October 1, 2012
• Added Section 7.3, “Access log delivery” [89].
4
May 1, 2015
Revision Date
API v1
Summary of Changes
• Updated the authentication 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 the "Bulk importing of data" section.
June 1, 2012
• Added Section 8.6, “Object versioning” [100].
• Added Chapter 11, “Static websites using CDN-enabled containers” [126].
April 25, 2012
• Added Section 13.1, “TempURL ” [134].
• Added Section 13.2, “FormPost” [137].
February 6, 2012
• Revised content to clarify issues brought up in doc tickets. Formatted HEAD like other commands. Standardized on URL. Added expiring objects and service net information.
January 12, 2012
• Revised content to add information about expiring object functionality and to clarify issues
brought up in doc tickets, including adding more cross-references for finding language bindings.
November 15, 2011
• Revised information about how to perform a CDN purge, indicating that 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 the new streaming feature, including changing examples to match the streaming headers and URLs returned.
June 29, 2011
• In cURL authentication requests, changed X-Auth-Token to X-Auth-Key in examples.
June 15, 2011
• Added best practices for authentication tokens.
May 24, 2011
• Added information about new headers including CORS headers.
April 20, 2011
• Updated the HEAD operation to return a 200 response code instead of a 204 response code
on an object metadata request.
• Updated the TTL maximum value to 50 years instead of 3 days, the minimum TTL to 15 minutes (900 seconds), and the default to 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 the
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 access control list (ACL).
• 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 API documentation website at docs.rackspace.com.
5
May 1, 2015
API v1
For more details about the Cloud Files service, see http://www.rackspace.com/cloud/files/.
Related documents are available at the same site, as are links to official Rackspace support
channels, including Knowledge Center articles, forums, phone, chat, and email.
For information about the Rackspace language-specific APIs that you can use for Cloud
Files, see the Rackspace Cloud SDKs Software Development Kit Guide. Each language-specific API includes its own documentation (either HTML, PDF, or CHM) including code snippets
and examples to help you get started. For information about the language-specific APIs,
see Language-Specific API Bindings.
1.4. Pricing and service level
Cloud Files is part of the Rackspace Cloud and your use of it through the API is billed according to the pricing schedule at www.rackspace.com/cloud/public/files/pricing.
The service level agreement (SLA) for Cloud Files is available at Cloud Files SLA.
6
May 1, 2015
API v1
2. Concepts
Cloud Files is not a file system in the traditional sense. You cannot map or mount virtual
disk drives like you can with other forms of storage such as a SAN or NAS. Because Cloud
Files is a different kind of storage system, you should take a few moments to review the following key concepts in this section.
2.1. Accounts
The Cloud Files system is designed to be used by many different customers. Your user
account is your portion of the Cloud Files system. You must identify yourself with your
Rackspace Cloud user name and API access key. After you are authenticated, you have full
read/write access to the files stored under your account. To obtain a Cloud Files account
and enable your API access key, go to http://www.rackspacecloud.com/signup.
2.2. Authentication
Section 3.1, “Authentication” [11] describes how to authenticate against the Rackspace
Cloud Identity service to receive Cloud Files connection parameters and an authentication
token. The token must be passed to Cloud Files operations during the time that it is valid.
For more information about authentication, see the Cloud Identity Client Developer Guide,
v2.0 at http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Overviewd1e65.html.
Note
The language-specific APIs handle authentication, token passing, and HTTPS request/response communication.
2.3. Permissions
In Cloud Files, you have your own storage account and full access to that account.
You must authenticate with your credentials as described in Section 3.1, “Authentication” [11]. After you are authenticated, you can perform all Cloud Files operations within that account.
You can use Role Based Access Control (RBAC) with Cloud Files. For more information, see
Section 3.2, “Role Based Access Control” [21].
2.4. Containers
A container is a storage compartment that provides a way for you to organize your data.
You can think of a container like a folder in Windows® or a directory in UNIX®. The primary difference between a container and these other file system concepts is that containers
cannot be nested. You can have up to 500,000 containers in your account. Data must be
stored in a container, so you must have at least one container defined in your account before you upload data.
7
May 1, 2015
API v1
If you expect to write more than 100 objects per second to a single container, we recommend organizing those objects across multiple containers to improve performance.
The only restrictions on container names is that they cannot contain a forward slash (/) and
must be less than 256 bytes in length. Note that the length restriction applies to the name
after it has been URL-encoded. For example, a container name of Course Docs would be
URL-encoded as Course%20Docs and is therefore 13 bytes in length rather than the expected 11.
You can create a container in any Rackspace data center. (See Section 3.3, “Service access
endpoints” [22] for a list.) However, in order to lower your costs, you should create
your most served containers in the same data center as your server. Otherwise, you will be
billed for external bandwidth charges. Note that this is true when computations are performed on objects but is not true for static content served to end users directly.
In addition to containing objects, you can also use the container to control access to objects
by using an access control list (ACL). For more information, see Section 7.1, “Container access control lists” [87]. You cannot store an ACL with individual objects.
2.5. Objects
Objects are the basic storage entities in Cloud Files. They represent the files and their optional metadata that 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 that you assign, consisting of key/value pairs.
For example, you can choose to store a backup of your digital photos and organize them
into albums. In this case, each object could be tagged with metadata such as Album :
Caribbean Cruise or Album : Aspen Ski Trip.
The only restriction on object names is that they must be less than 1024 bytes in length after URL-encoding. For example, an object name of C++final(v2).txt would be URL-encoded as C%2B%2Bfinal%28v2%29.txt and therefore is 24 bytes in length rather than
the expected 16.
Cloud Files limits 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 use 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. Segmentation also offers much greater upload speed with the possibility of parallel uploads of the segments.
For metadata, do not exceed 90 individual key/value pairs for any one object and do not
exceed 4 KB (4096 bytes) for the total byte length of all key/value pairs.
2.6. Operations
Operations are the actions you perform within your account, such as creating or deleting
containers or uploading or downloading objects. The full list of operations is given in Chapter 5, “API operations for storage services” [30]. The operations are then described in
the following REST API sections:
• Section 5.1, “Account services” [31]
8
May 1, 2015
API v1
• Section 5.2, “Container services” [43]
• Section 5.3, “Object services” [62]
You can perform operations through the REST web service API or a language-specific API.
(For information about the Rackspace language-specific APIs, see the Rackspace Cloud SDKs
Software Development Kit Guide.)
Important
All operations must include a valid authorization token.
2.7. CDN-enabled containers
CDN-enabled containers serve content through the Akamai content delivery network
(CDN). CDN-enabled containers are publicly accessible for read access, so they do not require an authorization token for read access. However, uploading content into a CDN-enabled container is a secure operation and requires a valid authentication token.
Each CDN-enabled container has a unique URI that can be combined with its object names
and openly distributed in web pages, emails, or other applications.
For example, a CDN-enabled container named photos might be referenced as
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com. If that container houses a screenshot called
wow1.jpg, that image can be served by a CDN with the full URL of
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.
rackcdn.com/wow1.jpg.
This URI can be embedded in items like HTML pages, email messages, or blog posts. The
first time that the URI is accessed, a copy of that image is fetched from the Cloud Files storage system. The copy is cached in a CDN and served from there for all subsequent requests
for a configurable cache time to live (TTL) value. Setting the TTL of a CDN-enabled container translates to setting the Expires and Cache-Control HTTP headers. Note that extremely long TTL values do not guarantee that an object is served from a CDN edge location. When the TTL expires, the CDN checks Cloud Files to ensure that it has the most up-todate content. A purge request forces the CDN to check with Cloud Files for the most up-todate version of the file.
Cloud Files continues to serve content through the CDN until it receives a delete request.
Note
For more information about TTL, including its default, minimum, and maximum
values, see Section 9.3, “CDN object services” [117].
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 CDNenabled even if it does not exist in the storage system. You might want the ability to pregenerate CDN URLs before actually uploading content, and this separation gives you that
ability.
9
May 1, 2015
API v1
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 CDNenable a container called images and be assigned the CDN URI, but you also need to create a container called images in the storage service.
For more information about CDN-enabled containers and operations for them, see Chapter 9, “API operations for CDN services” [105]
2.8. Language-specific APIs
APIs in several popular languages are available to help put Cloud Files in the hands of developers. These language-specific APIs provide a layer of abstraction on top of the base REST
API, enabling developers to work with a container and object model instead of working directly with HTTP requests and responses. The language-specific APIs are available at no cost
to download, use, and modify. They are licensed under the MIT license as described in the
COPYING file packaged with each API.
If you make any improvements to a Cloud File language-specific API, you are encouraged
(but not required) to submit those changes back to Rackspace. If you want to suggest
changes to an API, send an email to [email protected]. Be sure to indicate which
language and version you modified and send a unified diff.
Detailed information about the language-specific APIs is in the Rackspace Cloud SDKs Software Development Kit Guide. Each API has its own documentation (in HTML, PDF, or CHM
format) including code snippets and examples to help you get started.
You are welcome to create your own language-specific APIs. Rackspace will help answer
any questions during development, host your code if you like, and give you full credit for
your work.
10
May 1, 2015
API v1
3. General API information
The information in this chapter is relevant to all Cloud Files API operations. For information
about a specific API operation, see later chapters.
3.1. Authentication
Every REST request against the Cloud Files service requires the inclusion of a specific authorization token, supplied by the X-Auth-Token HTTP header. You obtain this token by using the Rackspace Cloud Identity service and supplying a valid user name and API access
key.
3.1.1. Geographic endpoints
The Rackspace Cloud Identity service serves as the entry point to all Rackspace Cloud APIs
and is itself a RESTful web service.
Use the following global endpoint to access the Rackspace Cloud Identity service:
• https://identity.api.rackspacecloud.com/v2.0/
3.1.2. Retrieving the authentication token
POST
v2.0/tokens
Authenticate to receive a token and a service catalog.
Normal Status Code(s): 200, 203
Error Status Code(s): unauthorized (401), userDisabled (403), badRequest (400), authFault
(500), serviceUnavailable (503)
The authenticate operation provides clients with an authentication token and a list of regional cloud endpoints.
Note
For information about how to use cURL to retrieve the authentication token,
see the Cloud Files Getting Started Guide.
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.
Note
If you authenticate with username and password credentials, you can use
multi-factor authentication to add an additional level of account security. This
11
May 1, 2015
API v1
feature is not implemented for the username and apiKey credentials shown
in the following examples.
For more information, see Multi-factor authentication in the Cloud Identity
Client Developer Guide.
Example 3.1. Authentication 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="yourUserName"
apiKey=" yourApiKey"/>
</auth>
Example 3.2. Authentication 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": "yourUserName",
"apiKey": "y ourApiKey"
}
}
}
The username is your common Rackspace Cloud username.
The key is your API access key.
To find your API key:
1. Log in to the Cloud Control Panel (https://mycloud.rackspace.com).
2. On the upper-right side of the top navigation pane, click your username.
3. From the menu, select Account Settings.
4. In the Login Details section of the Account Settings page, locate the API Key field
and click Show.
12
May 1, 2015
API v1
5. Copy the value of the API Key and paste it into a text editor of your choice.
6. Click Hide to hide the value of the API Key.
You also need your cloud account number. In the documentation, the account number is often referred to as your tenant name or tenant ID (technically, the ID is different from the name, but at Rackspace, they are the same thing). Together, three components—your username, your API Key, and your tenant ID or cloud account number—
form the authentication credentials that are required to connect to the Rackspace
cloud.
To find your tenant ID or cloud account number, locate your username on the upper-right side of the top navigation pane in the Cloud Control Panel. The tenant ID or
account number is in parentheses just to the right of your username.
Note
For Cloud Files, the information used in place of the account number
with the API operations is the MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee information found in the service catalog of
your authentication response, rather than the account number found in
the Cloud Control Panel.
Example 3.3. Authentication response: XML
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:50:20 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<access xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/
v1.0"
xmlns="http://docs.openstack.org/identity/api/v2.0"
xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
xmlns:common="http://docs.openstack.org/common/api/v1.0"
xmlns:ksgrp="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
xmlns:rax-kscatalog="http://docs.openstack.org/identity/api/ext/OSKSCATALOG/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<token id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" expires="2012-04-13T18:50:20.
000-06:00"/>
<user id="123456" name="yourUserName" 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"/>
13
May 1, 2015
API v1
<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-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="SYD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://storage101.syd2.clouddrive.com/v1/
internalURL="https://snet-storage101.syd2.clouddrive.com/v1/
<endpoint region="IAD"
publicURL="https://storage101.iad3.clouddrive.com/v1/
internalURL="https://snet-storage101.iad3.clouddrive.com/v1/
<endpoint region="ORD"
publicURL="https://storage101.ord1.clouddrive.com/v1/
internalURL="https://snet-storage101.ord1.clouddrive.com/v1/
<endpoint region="HKG"
publicURL="https://storage101.hkg1.clouddrive.com/v1/
14
May 1, 2015
API v1
internalURL="https://snet-storage101.hkg1.clouddrive.com/v1/
</service>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
<endpoint region="SYD"
<endpoint region="IAD"
<endpoint region="HKG"
<endpoint region="ORD"
</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. Authentication 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": "2012-04-13T18:45:13.000-06:00",
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"user": {
"id": "123456",
"name": "userUserName",
"RAX-AUTH:defaultRegion": "DFW",
"roles": [
{
"description": "Admin Role.",
"id": "identity:admin",
"name": "identity:admin"
},
{
"description": "Default Role.",
"id": "identity:default",
"name": "identity:default"
15
May 1, 2015
API v1
}
]
},
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://dfw.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.databases.api.
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudDatabases",
"type": "rax:database"
},
{
"endpoints": [
{
"publicURL": "https://dfw.loadbalancers.api.
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.loadbalancers.api.
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudLoadBalancers",
"type": "rax:load-balancer"
},
{
"endpoints": [
{
"tenantId": "1100111",
"region": "DFW",
"publicURL": "https://dfw.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://dfw.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://dfw.servers.api.
rackspacecloud.com/"
},
{
"tenantId": "1100111",
"region": "ORD",
"publicURL": "https://ord.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
16
May 1, 2015
API v1
"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": [
{
"publicURL": "https://cdn1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "DFW",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"region": "SYD",
},
{
"region": "IAD",
},
{
"region": "HKG",
},
{
"region": "ORD",
17
May 1, 2015
API v1
}
],
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"internalURL": "https://snet-storage101.dfw1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"publicURL": "https://storage101.dfw1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "DFW",
},
{
"internalURL": "https://snet-storage101.syd2.
"publicURL": "https://storage101.syd2.clouddrive.com/
v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880321",
"region": "SYD",
},
{
"internalURL": "https://snet-storage101.iad3.
"publicURL": "https://storage101.iad3.clouddrive.com/
"region": "IAD",
},
{
"internalURL": "https://snet-storage101.ord1.
"publicURL": "https://storage101.ord1.clouddrive.com/
"region": "ORD",
},
{
"internalURL": "https://snet-storage101.hkg1.
"publicURL": "https://storage101.hkg1.clouddrive.com/
"region": "HKG",
}
],
"name": "cloudFiles",
"type": "object-store"
},
{
"endpoints": [
18
May 1, 2015
API v1
{
"tenantId": "1100111",
"publicURL": "https://dns.api.rackspacecloud.com/v1.0/
1100111"
}
],
"name": "cloudDNS",
"type": "rax:dns"
}
]
}
}
Note
The information shown in the authentication response examples is for US-based
accounts. If you authenticate against the UK endpoint, you 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. An authentication token's default lifespan is 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.
The token's expires attribute denotes the time after which the token automatically
becomes invalid. A token can be manually revoked before the time identified by the
expires attribute. The attribute predicts a token's maximum possible lifespan but
does not guarantee that it will reach that lifespan. Clients are encouraged to cache a
token until it expires.
Users can be assigned a default region. If multiple endpoints are associated with a service in the user's catalog, the endpoint for the user's default region is selected if it is
available. In this example, the user's default region is DFW, and several of the services
in the catalog are associated with endpoints in that region. Whenever possible, the
user's work is directed to the DFW region.
Users can be assigned multiple roles, with each role providing specific privileges. In this
example, yourUserName is the administrative user for the account and holds the fully-privileged identity:admin role. Other users might hold other roles with different
privileges. Roles do not have to be associated with actual job functions such as Administrator, Operator, Developer, Tester, or Trainer.
The service catalog lists the services that you can access. In this example, the user can
access one database service, one load-balancing service, two compute services (Cloud
Servers OpenStack and Cloud Servers), two object storage services (Cloud Files CDN
and Cloud Files), and one DNS service. The catalog entry for each service provides at
least one endpoint URI for that service. Other information, such as regions, versions,
and tenants, is provided if it is relevant to a user's access to a service.
The service type attribute identifies services that perform similar functions, regardless of service names. In this example, the service named cloudFiles is identified as
19
May 1, 2015
API v1
type="object-store", identifying it as a storage service even though the word
"store" does not appear in its name.
Important
Use the service type attribute as the primary value for locating a service.
If multiple endpoints of the same service type exist in the same region, use
the service name attribute to locate the appropriate service.
The service name attribute identifies each unique service in the catalog. After a service
is created, its name does not change. However, new services of the same service type
can be added to the catalog with new names.
Important
If you are programmatically parsing an authentication response, use service type rather than service name to determine whether a user has access to a particular kind of service. Service type is stable across all releases.
New service types might be developed, but existing service types are not
renamed. In this example, type="compute" identifies all the available
compute services. If new compute services are added in future releases,
you can recognize them by parsing for type="compute" in the authentication response's service catalog.
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), see the Cloud Identity Client Developer Guide at http://
docs.rackspace.com/.
A service might expose endpoints in different regions. Regional endpoints enable
users 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 recognizes 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 that
you are using.
An endpoint can be assigned public and internal URIs. A public URI is accessible from
anywhere. Access to a public URI usually incurs traffic charges. Internal URIs are accessible only to services within the same region. Access to an internal URI is free of
charge.
20
May 1, 2015
API v1
Cloud Files service endpoints are published in the service catalog in the authentication response with the account information, which is a required element of the service endpoints.
The examples shown in this document are for authentication for US customers. Customers
with UK-based accounts see different values in the service catalog. For more information
about service endpoints, see Section 3.3, “Service access endpoints” [22].
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” [21]). The permissions to perform certain operations in the Cloud Files API – create, read, update, delete – are assigned to specific roles,
and the Cloud account admin user assigns these roles to account users.
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.
For information about how to perform the following tasks, see the Cloud Identity Client Developer Guide:
• 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.
21
May 1, 2015
API v1
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.
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 and
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:
Appears that the user has only the
multiproduct observer and Cloud Files multiproduct observer role
admin
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
Yes, for all of the products. The Cloud
Files observer role is ignored.
Appears that the user has only the
multiproduct admin role
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, see the Permissions Matrix for Cloud Files article
in the Rackspace Knowledge Center.
3.3. Service access endpoints
Cloud Files is a regionalized service. You can create your Cloud Files containers in any
Rackspace data center. The user of the service is therefore responsible for appropriate replication, caching, and overall maintenance of Cloud Files data across regional boundaries to
other Cloud Files servers.
To help you decide which regionalized endpoint to use, read the Knowledge Center article
about special considerations for choosing a data center at About Regions.
The endpoints to use for the storage service component of your Cloud Files API calls are
summarized in the following table. The first endpoint listed for each region is externally accessible. The second endpoint is accessed only from the internal ServiceNet.
22
May 1, 2015
API v1
Table 3.3. Regionalized service endpoints for storage services
Region
Chicago (ORD)
Endpoint
https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.ord1.clouddrive.com/
Dallas/Ft. Worth (DFW)
https://storage101.dfw1.clouddrive.com/
https://snet-storage101.dfw1.clouddrive.com/
Hong Kong (HKG)
https://storage101.hkg1.clouddrive.com/
https://snet-storage101.hkg1.clouddrive.com/
London (LON)
https://storage101.lon3.clouddrive.com/
https://snet-storage101.lon3.clouddrive.com/
Northern Virginia (IAD)
https://storage101.iad3.clouddrive.com/
https://snet-storage101.iad3.clouddrive.com/
Sydney (SYD)
https://storage101.syd2.clouddrive.com/
https://snet-storage101.syd2.clouddrive.com/
Note
ServiceNet endpoints
If you are working with cloud servers that are in one of the Rackspace data
centers, using the ServiceNet endpoint in the same data center has no network costs and provides a faster connection. ServiceNet endpoints are prefixed
with snet- in Table 3.3, “Regionalized service endpoints for storage services
” [23]. ServiceNet is the data center internet network. In your authentication response, it is listed as internalURL.
Public endpoints
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.
Replace the sample MossoCloudFS information in the preceding table with the actual
MossoCloudFS information returned as part of the authentication service response. This information is located after the final '/' in the publicURL field and the internalURL field
in the cloudFiles section of the service catalog returned by the authentication response.
For more information about the account number, see the sample authentication request
23
May 1, 2015
API v1
and response in Section 3.1.2, “Retrieving the authentication token” [11] as well as the
Cloud Identity Client Developer Guide.
Tip
If you do not know which data center you are working in or your account ID,
you can find them in your Cloud Control Panel at mycloud.rackspace.com.
Note
To avoid external bandwidth charges, your containers and servers must be in
the same data center.
You might find it useful to locate your objects in more than one data center to
keep track of your data and backups. Specifically, if you serve an audience in a
particular region, you might find it helpful to locate your Cloud Files objects as
close to that region as possible.
The endpoints to use for the CDN management service component of your Cloud Files API
calls are summarized in the following table.
Note
If your audience is worldwide, consider using the Akamai content delivery network (CDN). The CDN speeds your content delivery because it is cached at edge
locations around the globe, rather than being served from a single origin server. You can learn more about CDN-enabling your containers in Chapter 9, “API
operations for CDN services” [105].
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)
Hong Kong (HKG)
London (LON)
Northern Virginia (IAD)
Sydney (SYD)
As with the storage component service, replace the sample MossoCloudFS information with
the actual MossoCloudFS information returned as part of the authentication service response. For the CDN management service, this information is located after the final '/' in
the publicURL field in the cloudFilesCDN section of the service catalog returned by
the authentication response.
24
May 1, 2015
API v1
3.4. Cloud Files service contract version
The Cloud Files version defines the contract and build information for the API.
The contract version denotes the data model and behavior that the API supports. The requested contract version is included in all request URIs. Different contract versions of the
API might be available at any given time and are not guaranteed to be compatible with
one another.
Example 3.5. Example request URL (contract version in bold)
https://storage101.dwf1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-ccccdddd-eeeeeeeeeeee
Note
This document pertains to contract version 1.
3.5. Absolute limits
Absolute limits control the total number of specific objects that a user can have or process
in Cloud Files. Absolute limits are fixed.
The following table lists the absolute limits in Cloud Files.
Table 3.5. Absolute limits
Name
Description
Limit
Containers per account
Maximum number of containers per account
500,000 containers
Container listing
Maximum number of containers that can be listed at 10,000 containers
one time
Pseudo hierarchical folders and di- Simulated hierarchical structure within a single conrectories
tainer, created by adding a forward slash (/) in the
object name
No limit
Account, container, and object
metadata limits
Maximum metadata limits
90 distinct metadata items
at the most. Each piece
of metadata can have a
128-character name length
with a 256 maximum value
length. The total length of
all names and values cannot
exceed 4096 bytes.
Number of object segments per
static 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 (31,536,000 seconds)
Container name length
Maximum length of container name
256 bytes
Object name length
Maximum length of object name
1024 bytes
Upload limit for a request
Maximum object size for an upload in a single request
5 GB (For larger files, see
Section 8.2.2, “Creating a
static large object” [95])
or Section 8.2.1, “Creating a dynamic large object” [93].)
25
May 1, 2015
API v1
Name
Description
Limit
CDN file size limit
Maximum size of file that can be served from CDN
10 GB
Rate limit for write operations
Maximum number of write operations per second
100 write operations per
per container, where a write operation is a COPY,
second per container
DELETE, POST, or PUT. If you reach this rate limit,
Cloud Files slows the processing of write requests for
the container to 100 write operations per second
per container.
3.6. Request and response types
You specify the request format by using the Content-Type header. The Cloud Files API
supports both the JSON (application/json) and XML (application/xml) data serialization formats, as well as other formats such as text/plain, text/xml, and text/
html, along with video, audio, and image types. For pseudo hierarchical folders and directories, application/directory might be used.
You specify the response format in requests by using the Accept header. The Cloud Files
API supports both the JSON (application/json) and XML (application/xml) data
serialization formats, as well as other formats such as text/plain and text/xml .
3.7. Response codes
Cloud Files returns an HTTP code that denotes the type of response.
The following table lists possible responses with their associated codes and descriptions.
Response
Associated response code
Description
OK
200
The request has succeeded. (Some API calls might return
201 instead.)
Created
201
The request has been fulfilled and a resource was created.
Accepted
202
The request has been accepted for processing.
No Content
204
The request has been fulfilled but does not return a representation (that is, the response is empty).
Partial Content
206
The server has fulfilled the partial GET request for the resource.
Bad Request
400
The request was not understood due to bad syntax or
missing required parameters.
Unauthorized
401
Authentication failed, or the user does not have permissions for a requested operation.
Forbidden
403
The server understood the request but refused to fulfill it.
Not Found
404
A requested resource was not found but might be available again in the future..
Method Not Allowed
405
The request method is not supported for this resource.
Request Timeout
408
The server timed out waiting for the request.
Conflict
409
The request could not be completed due to a conflict with
the current state of the resource.
Length Required
411
The request did not specify the length of its content,
which is required by the requested resource.
Precondition Failed
412
The server does not meet one of the preconditions that
the requester put on the request.
26
Response
May 1, 2015
Associated response code
API v1
Description
Request Entity Too Large
413
The server is refusing to process a request because the request entity is larger than the server is willing or able to
process.
Expectation Failed
417
The server cannot meet the requirements of the Expect request-header field.
Unprocessable Entity
422
The request could not be followed due to semantic errors.
Too Many Requests
429
Too many requests have been sent in a given amount
of time. Pause requests, wait up to one minute, and try
again. (Intended for use with rate limiting.)
Internal Server Error
500
The service encountered an unexpected condition that
prevented it from fulfilling the request.
Service Unavailable
503
The service is currently unable to handle the request due
to a temporary overloading or maintenance. This is a temporary condition. Try again later.
An example of an error message follows.
Example 3.6. Error message example
HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: 8a964ee2a5e88be344f36c22562a6486
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
27
May 1, 2015
API v1
4. Overview of API operations
The Cloud Files API is implemented as a set of RESTful web services. All authentication and
container/object operations can be performed with standard HTTP calls. For more information about REST, see Representation State Transfer.
The following constraints apply to REST API HTTP requests:
• Maximum number of HTTP headers per request: 90
• Maximum length of all HTTP headers: 4096 bytes
• Maximum length per HTTP request line: 8192 bytes
• Maximum length of HTTP request: 5 gigabytes
• Maximum length of container name: 256 bytes
• Maximum length of object name: 1024 bytes
Container and object names must be UTF-8 encoded and then URL-encoded before interacting with the REST interface. You might be using an API binding that performs the URLencoding on your behalf. If so, do not URL-encode before calling the API binding, or you
will double-encode container and object names. Check the length restrictions against the
URL-encoded string.
Note
The language-specific APIs handle URL-encoding and decoding.
Each REST request against Cloud Files requires the inclusion of an authorization token in
the X-Auth-Token header. You obtain this token, along with the Cloud Files URIs, by first
using the Rackspace authentication service and supplying a valid user name and API access
key. For more information, see Section 3.1, “Authentication” [11].
The following services make up the full Cloud Files product :
• Storage service: The service identified with cloudFiles in the service catalog (see Section 3.1.2, “Retrieving the authentication token” [11]) manages the data storage in the
system. Example operations are creating containers and uploading objects.
• CDN management service: The service identified with cloudFilesCDN in the service
catalog (see Section 3.1.2, “Retrieving the authentication token” [11]) manages the CDN
feature of Cloud Files.
28
May 1, 2015
API v1
In the following sections, the purpose of each HTTP method depends on 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 cloudFilesCDN endpoints is used to CDN-enable a container.
The language-specific APIs mask this system separation. They simply create a container and
mark it public and handle calling the appropriate back-end services by using the appropriate REST APIs.
Note
All requests to authenticate and operate against Cloud Files are performed using SSL over HTTP (HTTPS) on TCP port 443.
The following diagram illustrates the various system interfaces and the ease with which
content can be distributed over the CDN. The process is simple: authenticate, create a container, upload objects, mark the container as public, and begin serving that content from a
powerful CDN.
Note
Marking the container as public simply means enabling the container to be distributed over the CDN. A CDN-enabled container is publicly accessible.
Figure 4.1. Cloud Files system interfaces
29
May 1, 2015
API v1
5. API operations for storage services
This chapter describes each of the API operations provided by the Cloud Files service.
All requests are directed to the endpoints described in the cloudFiles section of the service catalog obtained during successful authentication. (For more information, see Section 3.1, “Authentication” [11] and Section 3.3, “Service access endpoints” [22].)
Following are some requirements for the storage services component:
• Object and container names must be URL-encoded and UTF-8 encoded.
• Container names cannot exceed 256 bytes and cannot contain a forward slash (/).
• Object names cannot exceed 1024 bytes, but they have no character restrictions.
The following sections describe the operations that you can perform within the storage system:
• Section 5.1, “Account services” [31] describes operations that you can perform at the
account level of the storage system.
• Section 5.2, “Container services” [43] describes operations that you can perform on
containers.
• Section 5.3, “Object services” [62] describes operations that you can perform on objects.
Method
URI
Description
Account services
GET
/v1/{account}{?limit,marker,
end_marker,format,prefix,delimiter}
Shows details for a specified account and lists containers,
sorted by name, in the account.
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}
Shows details for a specified container and lists objects,
sorted by name, in the container.
PUT
/v1/{account}/{container}
Creates a container.
DELETE
Deletes an empty container.
POST
Creates or updates the container metadata by associating custom metadata headers with the container-level
URI. These headers must have the format X-Container-Meta-name.
HEAD
Shows container metadata, including the number of objects in the container and the total bytes for all objects
stored in the container.
POST
Deletes container metadata.
GET
/v1/{account}/{container}/{object} Gets the content and metadata for the object.
{?signature,expires,multipart-manifest}
Object services
30
Method
May 1, 2015
URI
API v1
Description
PUT
/v1/{account}/{container}/{object} Creates or updates the content and metadata for a speci{?signature,expires,multipart-man- fied object.
ifest}
DELETE
/v1/{account}/{container}/{object} Permanently deletes an object from the Cloud Files stor{?multipart-manifest}
age system. (You can use COPY and then DELETE to effectively move an object.)
COPY
/v1/{account}/{container}/{object} Using the Destination header, copies an existing object
to another object with a new name in the Cloud Files storage system.
HEAD
/v1/{account}/{container}/{object} Shows object metadata.
{?signature,expires}
POST
/v1/{account}/{container}/{object} Sets or updates your object metadata. Metadata must be
in the format X-Object-Meta-name where name is the
name of your metadata. You can also assign X-DeleteAt or X-Delete-After to expiring objects.
5.1. Account services
You can perform the operations in the following table at the account level of your Cloud
Files account.
The examples in this section use sample values for the following:
• account — for example, MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123
• X-Auth-Token — for example, f064c46a782c444cb4ba4b6434288f7c
For your own requests, you must use your own account information and authentication token. For more information, see Section 3.1.2, “Retrieving the authentication token” [11].
Your authentication token and your account information are in the service catalog that is
produced.
Method
URI
Description
GET
POST
/v1/{account}
HEAD
/v1/{account}
POST
/v1/{account}
31
May 1, 2015
API v1
5.1.1. Show account details and list containers
Method
GET
URI
Description
This operation lists the storage containers in your account and sorts them by name. You
perform the operation against your storage account URL.
The list is limited to 10,000 containers at a time. For information on limiting and navigating
the list, see the following section, "Controlling a Large List of Containers".
Container names are sorted based on a binary comparison, a built-in collating function that
compares string data by using SQLite's memcmp() function, regardless of text encoding. For
more information, see http://www.sqlite.org/datatype3.html#collation.
A list of containers is returned in the response body, one container per line.
The character sequence used to create the newline that separates the container names is a
single \n. If you want to parse these listings, you send an Accept: application/json
or Accept: application/xml header with the request to get the results in JSON or
XML.
An HTTP response status code of 200 through 299 indicates success. A 200 (OK) code is returned if there are containers, and a 204 (No Content) code is returned if there are no containers.
Format Container List
If you append the ?format=xml or ?format=json query parameter to the storage account URL, the service returns container information serialized in the specified format. To
format your results, you must place this query parameter before any other parameters.
The example responses in this section are formatted for readability.
Controlling a Large List of Containers
A GET operation on the storage account URL returns a list of up to 10,000 container names.
You can control and limit this list of results by using the marker, end_marker, and limit
parameters. These parameters provide a mechanism for iterating through the entire list of
containers.
The marker parameter tells Cloud Files where to begin your list of containers, and the
end_marker parameter specifies where to end the list. You can use them independently
or together, separated by an ampersand (&). If you do not specify them, your list displays
up to 10,000 containers. Note that the marker and end_marker values must be URL-encoded before you send the HTTP request.
You can use the limit parameter to reduce the number of returned objects.
If the number of returned items equals the limit used (or 10,000 if no limit was specified), you can assume there are more object names.
32
May 1, 2015
API v1
Note
At this time, a prefix query parameter is not supported at the account level.
As an example, start with an account that has five container names, as follows:
apples
bananas
kiwis
oranges
pears
Use a limit of 2 to show how things work:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
apples
bananas
Because the operation returned two items, assume there are more container names to list
and make another request with a marker of the last item returned:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=
bananas
kiwis
oranges
Again, two items are returned, and you assume that there might be more. So you make another GET request for two more:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?limit=2&marker=
oranges
pears
This one-item response shows fewer than the limit of 2 container names requested, and indicates that this is the end of the list.
By using the end_marker parameter, you can limit the result set to container names less
than the given value.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?end_marker=oranges
apples
bananas
kiwis
This table shows the possible response codes for this operation:
33
Response
Code
May 1, 2015
Name
API v1
Description
200
OK
The request succeeded. The information returned with the response is
dependent on the method used in the request.
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
404
Not Found
The requested resource was not found.
5.1.1.1. Request
This table shows the header parameters for the show account details and list containers request:
Name
X-Auth-Token
Type
String
Description
Authentication token.
(Required)
String
Accept
(Optional)
Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.
This table shows the URI parameters for the show account details and list containers request:
Name
Type
String
{account}
Description
Your unique account identifier.
This table shows the query parameters for the show account details and list containers request:
Name
limit
Type
Int
Description
For an integer value n, limits the number of results to n values.
(Optional)
marker
String
(Optional)
end_marker
String
(Optional)
format
String
Given a string value x, returns container names greater in value than
the specified marker. Only strings using UTF-8 encoding are valid.
Given a string value x, returns container names lesser in value than the
specified marker. Only strings using UTF-8 encoding are valid.
Value of the serialized response format, either JSON or XML.
(Optional)
prefix
String
Prefix value. Object names in the response begin with this value.
(Optional)
delimiter
Char
(Optional)
Delimiter value, which returns the object names that are nested in the
container.
Example 5.1. Show account details and list containers: XML request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=xml HTTP/1.1
34
May 1, 2015
API v1
Example 5.2. Show account details and list containers: JSON request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=json HTTP/1.1
This operation does not accept a request body.
5.1.1.2. Response
This table shows the header parameters for the show account details and list containers response:
Name
Type
Content-Length
String
Content-Type
String
(Required)
X-Account-Object-Count
Description
The length of the response body that contains the list of names. If the
operation fails, this value is the length of the error text in the response
(Required) body.
Int
The MIME type of the list of names. If the operation fails, this value is
the MIME type of the error text in the response body.
The number of objects in the account.
(Required)
X-Account-Bytes-Used
Int
(Required)
X-Account-Container-Count Int
The total number of bytes that are stored in Cloud Files for the account.
The number of containers.
(Required)
X-Account-Meta-name
String
The custom account metadata item, where name is the name of the
metadata item. One X-Account-Meta-name response header ap(Optional) pears for each metadata item (for each name).
X-Account-Meta-Temp-URLKey
String
X-Account-Meta-Temp-URLKey-2
String
X-Trans-Id
Uuid
(Optional)
(Optional)
The secret key value for temporary URLs. If not set, this header is not
returned by this operation.
A second secret key value for temporary URLs. If not set, this header is
not returned by this operation.
A unique transaction identifier for this request.
(Required)
Datetime
Date
The transaction date and time.
(Required)
This table shows the body parameters for the show account details and list containers response:
Name
name
Type
String
Description
Name of the container.
(Required)
count
Int
Number of objects in the container.
(Required)
bytes
Int
Number of bytes in the container.
(Required)
35
May 1, 2015
Example 5.3. Show account details and list containers: XML response
HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT
<account name="my_account">
<container>
<name>janeausten</name>
<count>0</count>
<bytes>0</bytes>
</container>
<container>
<name>marktwain</name>
<count>1</count>
<bytes>14</bytes>
</container>
</account>
This list shows the body parameters for the response:
• *:
• name: Xsd:string. Required.
Name of the container.
• count: Xsd:int. Required.
Number of objects in the container.
• bytes: Xsd:int. Required.
Example 5.4. Show account details and list containers: JSON response
HTTP/1.1 200 OK
Content-Length: 96
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT
36
API v1
May 1, 2015
[
{
"count": 0,
"bytes": 0,
"name": "janeausten"
},
{
"count": 1,
"bytes": 14,
"name": "marktwain"
}
]
This operation does not return a response body.
37
API v1
May 1, 2015
API v1
5.1.2. Create or update account metadata
Method
POST
URI
Description
/v1/{account}
You can associate custom metadata headers with the account level URI. To create or update an account metadata header, submit a POST operation. These headers must have
the format X-Account-Meta-name. Replace name with name of your metadata. (In the
following example request, the metadata headers are X-Account-Meta-Book and XAccount_Meta-Subject.)
Subsequent POST operations for the same key/value pair overwrite the previous value.
A status code of 200 through 299 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 Get account metadata.) Do not send the metadata in your HEAD operation.
Response
Code
Name
Description
204
No Content
400
Bad Request
The request could not be understood by the server due to malformed
syntax.
5.1.2.1. Request
This table shows the header parameters for the create or update account metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
String
String
X-Account-Meta-name
String
The secret key value for temporary URLs.
(Optional)
A second secret key value for temporary URLs. The second key enables
you to rotate keys by having an old and new key active at the same
(Optional) time.
Account metadata that you want to create or update. Replace name
at the end of the header with the name for your metadata. You must
(Required) specify a X-Account-Meta-name header for each metadata item
(for each name) that you want to add or update.
This table shows the URI parameters for the create or update account metadata request:
Name
{account}
Type
String
Description
38
May 1, 2015
API v1
Example 5.5. Create or update account metadata: HTTP request
POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1
X-Account-Meta-Book: MobyDick
X-Account-Meta-Subject: Whaling
5.1.2.2. Response
This table shows the header parameters for the create or update account metadata response:
Name
Content-Length
Type
String
(Required)
Content-Type
String
(Required)
X-Trans-Id
Uuid
Description
If the operation succeeds, this value is zero (0). If the operation fails,
this value is the length of the error text in the response body.
If the operation fails, this value is the MIME type of the error text in
the response body.
(Required)
Date
Datetime
(Required)
Example 5.6. Create or update account metadata: HTTP response
HTTP/1.1 204 No Content
Content-Length: 0
X-Trans-Id: tx1b4be419af2c4d688ee4d-0052cf1ea4dfw1
Date: Thu, 09 Jan 2014 22:11:48 GMT
39
May 1, 2015
API v1
5.1.3. Get account metadata
Method
HEAD
URI
Description
/v1/{account}
Perform a HEAD operation on your storage account URL to get the following information:
• The number of containers that you have in your account (X-Account-Container-Count)
• The number of objects that are stored in the containers in your account (X-Account-Object-Count)
• The total bytes that are stored for your account (X-Account-Bytes-Used)
An HTTP status code of 200 through 299 indicates success. In the example, a 204 (No Content) status code is returned. A 401 (Unauthorized) status code is returned for an invalid account or authentication token.
Response
Code
Name
Description
204
No Content
401
Unauthorized
Authentication has failed.
5.1.3.1. Request
This table shows the header parameters for the get account metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
X-Auth-Token
String
(Required)
This table shows the URI parameters for the get account metadata request:
Name
{account}
Type
String
Description
Example 5.7. Get account metadata: HTTP request
HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1
5.1.3.2. Response
This table shows the header parameters for the get account metadata response:
40
May 1, 2015
Name
X-Account-Object-Count
Type
Int
(Required)
X-Account-Bytes-Used
Int
(Required)
X-Account-Container-Count Int
(Required)
Content-Length
String
(Required)
Content-Type
String
(Required)
X-Trans-Id
Uuid
API v1
Description
The total number of objects that are stored in Cloud Files for the account.
The total number of bytes that are stored in Cloud Files for the account.
The total number of containers that are stored in the Cloud Files for
the account.
the response body.
(Required)
Date
Datetime
(Required)
Accept-Ranges
String
The type of ranges accepted.
(Required)
X-Account-Meta-name
String
The custom account metadata item, where name is the name of the
metadata item. One X-Account-Meta-name response header ap(Optional) pears for each metadata item (for each name).
String
String
(Optional)
(Optional)
The secret key value for temporary URLs. If not set, this header is not
returned by this operation.
A second secret key value for temporary URLs. If not set, this header is
not returned by this operation.
Example 5.8. Get account metadata: HTTP response
Content-Length: 0
X-Timestamp: 1369081921.78518
X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284e
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx8e82a77399724e40a90e8-0052cf0e52dfw1
Date: Thu, 09 Jan 2014 21:02:10 GMT
41
May 1, 2015
API v1
5.1.4. Delete account metadata
Method
POST
URI
Description
/v1/{account}
To delete a metadata header, use the POST operation to send an empty value for that particular header.
If the tool that you use to communicate with Cloud Files does not support empty headers,
such as an older version of cURL, send the X-Remove-Account-Meta-name: arbitrary value header. The arbitrary value is ignored. In the following example request, X-Remove-Account-Meta-Book: x is used.
A status code of 200 through 299 indicates success.
Response
Code
Name
Description
204
No Content
400
Bad Request
syntax.
5.1.4.1. Request
This table shows the header parameters for the delete account metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
String
String
X-Remove-Account-Metaname
String
The secret key value for temporary URLs.
(Optional)
A second secret key value for temporary URLs. The second key enables
you to rotate keys by having an old and new key active at the same
(Optional) time.
(Required)
Header to send to delete account metadata. Replace name at the end
of the header with the name for your metadata.
This table shows the URI parameters for the delete account metadata request:
Name
{account}
Type
String
Description
Example 5.9. Delete account metadata: HTTP request
42
May 1, 2015
API v1
X-Remove-Account-Meta-Book: x
5.1.4.2. Response
This table shows the header parameters for the delete account metadata response:
Name
Content-Length
Type
String
(Required)
Content-Type
String
(Required)
X-Trans-Id
Uuid
Description
the response body.
(Required)
Date
Datetime
(Required)
Example 5.10. Delete account metadata: HTTP response
Content-Length: 0
X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1
Date: Thu, 09 Jan 2014 22:28:22 GMT
5.2. Container services
You can perform the operations in the following table on containers in your Cloud Files account.
• container — for example, MyContainer
For your own requests, you must use your own account information, authentication token,
and container names. For more information, see Section 3.1.2, “Retrieving the authentication token” [11]. Your authentication token and your account information are in the service catalog that is produced.
Method
URI
Description
GET
delimiter,path}
PUT
DELETE
POST
43
Method
May 1, 2015
URI
API v1
Description
HEAD
POST
44
May 1, 2015
API v1
5.2.1. Show container details and list objects
Method
GET
URI
Description
delimiter,path}
This operation against a storage container name retrieves a list of the objects stored in the
container. You can use optional query parameters to refine the list results.
A request with no query parameters returns the full list of object names stored in the container, up to 10,000 names. The response body shows the object names as one object name
per line. Specifying the query parameters filters the full list and returns a subset of objects.
For information about limiting and controlling the list, see the following “Controlling a
Large List of Objects” section.
An HTTP response status code of 200 through 299 indicates success. A status code of 200
(OK) is returned if there are objects, and a 204 (No Content) is returned if there are no objects. If the container does not exist, or if an incorrect account is specified, a status code 404
(Not Found) is returned.
Format Object List
If you append the format=xml or the format=json query parameter to the storage account URL, the service returns additional object information serialized in the specified format. The status codes are the same for format=xml and format=json. However, Content-Type matches the specified format. The example responses in this section are formatted for readability.
Controlling a Large List of Objects
A GET request against the container account URL returns a list of up to 10,000 objects. You
can limit and control this list of results by using the marker, end_marker, and limit parameters.
The marker parameter tells Cloud Files where to begin your list of objects, and the
end_marker parameter tells where to end the list. You can use them either independently or together, separated by an ampersand (&). If you do not specify them, your list displays
up to 10,000 objects. Note that the marker and end_marker values must be URL-encoded before you send the HTTP request.
You can use the limit parameter to reduce the number of returned objects.
If the number of returned items equals the limit used (or 10,000 if no limit was specified), you can assume there are more object names.
As an example, use a listing of 5 object names, as follows:
gala
grannysmith
honeycrisp
jonagold
reddelicious
45
May 1, 2015
API v1
Use a limit of 2 to show how things work:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2
gala
grannysmith
Because the request returned two items, assume there are more object names to list and
make another request with a marker of the last item returned:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&
marker=grannysmith
honeycrisp
jonagold
Again, two items are returned, and you assume that there might be more. So you make another GET request for two more:
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2&
marker=jonagold
reddelicious
This one-item response shows fewer than the limit of two object names requested, and indicates that this is the end of the list.
Response
Code
Name
Description
200
OK
204
No Content
404
Not Found
409
Conflict
The request could not be completed due to a conflict with the current
state of the resource.
5.2.1.1. Request
This table shows the header parameters for the show container details and list objects request:
Name
X-Auth-Token
Type
String
Description
(Required)
Accept
String
Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.
46
May 1, 2015
Name
Type
API v1
Description
(Optional)
This table shows the URI parameters for the show container details and list objects request:
Name
Type
Description
{account}
String
{container}
String
The unique identifier of the container.
This table shows the query parameters for the show container details and list objects request:
Name
limit
Type
Int
Description
For an integer n, limits the number of results to n values.
(Optional)
marker
String
(Optional)
end_marker
String
(Optional)
prefix
String
(Optional)
format
String
(Optional)
delimiter
Char
(Optional)
path
Given a string value x, returns object names greater in value than the
specified marker.
Given a string value x, returns object names lesser in value than the
specified marker.
For a string value x, causes the results to be limited to object names
beginning with the substring x.
Specifies either JSON or XML to return the respective serialized response.
For a character c, returns the object names nested in the container
(without the need for the directory marker objects).
String
For a string x, returns the object names nested in the pseudo path.
This parameter is equivalent to setting the delimiter parameter to /
(Optional) and the prefix to the path with a / on the end. For more information
about pseudo paths, see the section on pseudo hierarchical folders
and directories.
Example 5.11. Show container details and list objects: XML request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=xml HTTP/1.1
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4
Example 5.12. Show container details and list objects: JSON request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=json HTTP/1.1
5.2.1.2. Response
This table shows the header parameters for the show container details and list objects response:
47
May 1, 2015
Name
Type
Content-Length
String
X-Container-Object-Count
Int
API v1
Description
(Required) body.
The number of objects.
(Required)
Accept-Ranges
String
The type of ranges that the object accepts.
(Required)
X-Container-Bytes-Used
Int
The count of bytes used in total.
(Required)
X-Container-Meta-name
String
The custom container metadata item, where name is the name of the
metadata item. One X-Container-Meta-name response header ap(Optional) pears for each metadata item (for each name).
Content-Type
String
(Required)
Uuid
X-Trans-Id
(Required)
Datetime
Date
(Required)
This table shows the body parameters for the show container details and list objects response:
Name
name
Type
String
Description
Name of the object.
(Required)
bytes
Int
(Required)
content-type
String
The content type of the container.
(Required)
last-modified
String
An internal variable that indicates the last time an entity (account,
container, or object) was modified. last-modified has resolution
(Required) up to one second. For last-modified, the time zone is UTC.
Example 5.13. Show container details and list objects: XML response
HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT
<container name="marktwain">
<object>
48
May 1, 2015
<name>goodbye</name>
<hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
<bytes>14</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:41:49.390270</last_modified>
</object>
<object>
<name>helloworld</name>
<hash>ed076287532e86365e841e92bfc50d8c</hash>
<bytes>12</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:37:43.427570</last_modified>
</object>
</container>
Example 5.14. Show container details and list objects: JSON response
HTTP/1.1 200 OK
Content-Length: 341
X-Timestamp: 1389727543.65372
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT
[
{
"hash":"451e372e48e0f6b1114fa0724aa79fa1",
"last_modified":"2014-01-15T16:41:49.390270",
"bytes":14,
"name":"goodbye",
"content_type":"application/octet-stream"
},
{
"hash":"ed076287532e86365e841e92bfc50d8c",
"last_modified":"2014-01-15T16:37:43.427570",
"bytes":12,
"name":"helloworld",
"content_type":"application/octet-stream"
}
]
49
API v1
May 1, 2015
API v1
5.2.2. Create container
Method
PUT
URI
Description
This operation creates a Cloud Files container. Containers are storage compartments for
your data. The URL-encoded name must be no more than 256 bytes and cannot contain a
forward slash character (/). You can create up to 500,000 containers in your Cloud Files account.
You can assign custom metadata for containers by including additional HTTP headers with
an X-Container-Meta- prefix on the POST request. For details on setting custom metadata, see Create or update account metadata.
Using custom container metadata, you can create information in the header to effectively
tag a container. The container metadata restrictions are the same as the restrictions for object metadata. You can have a maximum of 4096 bytes of metadata for the container, with
a maximum of 90 distinct metadata items. Each distinct metadata item can have a name
length of up to 128 characters with a maximum of 256 bytes in the value. Any valid UTF-8
encoded string value is allowed for metadata. In addition for custom metadata, we recommend that you URL-encode any non-ASCII values by using a % symbol followed by the twodigit hexadecimal ISO-Latin code for the character.
A status code of 201 (Created) indicates that the container was created as requested. Container PUT requests are idempotent, and a code of 202 (Accepted) is returned if the container existed prior to the request. If you make a PUT request to a container with an XContainer-Meta- prefix in the header, your GET or HEAD request responses carry the
metadata prefix from the container in subsequent requests.
Response
Code
Name
Description
201 202
Created or Accepted
The request has been fulfilled. For 201 Created, the new container has
been created. For 202 Accepted, the request has been accepted for
processing.
400
Bad Request
syntax.
5.2.2.1. Request
This table shows the header parameters for the create container request:
Name
X-Auth-Token
Type
String
Description
(Required)
String
(Optional)
Custom container metadata. Replace name at the end of the header
with the name for your metadata.
50
Name
May 1, 2015
Type
X-Container-Read
String
X-Container-Write
String
X-Versions-Location
String
API v1
Description
Sets an access control list (ACL) that grants read access. This header
can contain a comma-delimited list of users that can read the contain(Optional) er (allows the GET method for all objects in the container).
Sets an ACL that grants write access. This header can contain a comma-delimited list of users that can write to the container (allows PUT,
(Optional) POST, COPY, and DELETE methods for all objects in the container).
Enables versioning on this container. The value is the name of another
container. You must UTF-8-encode and then URL-encode the name be(Optional) fore you include it in the header. To disable versioning, set the header
to an empty string.
This table shows the URI parameters for the create container request:
Name
Type
Description
{account}
String
{container}
String
Example 5.15. Create container: HTTP request
PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1
Example 5.16. Create container with metadata: HTTP request
X-Container-Meta-InspectedBy: JackWolf
5.2.2.2. Response
This table shows the header parameters for the create container response:
Name
Type
Content-Length
String
Content-Type
String
(Required)
X-Trans-Id
Description
(Required) body.
Uuid
(Required)
Date
Datetime
(Required)
Example 5.17. Create container: HTTP response
Content-Length: 0
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
Date: Tue, 14 Jan 2014 19:09:10 GMT
51
May 1, 2015
Example 5.18. Create container with metadata: HTTP response
Content-Length: 0
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT
52
API v1
May 1, 2015
API v1
5.2.3. Delete container
Method
DELETE
URI
Description
A DELETE operation against a storage container permanently removes it. The container
must be empty before it can be deleted.
Before using DELETE, you can use a GET operation against the container to list any objects
that it contains. (See Show container details and list objects.)
A status code of 204 (No Content) indicates success. A status code of 404 (Not Found) is returned if the requested container is not found. A status code of 409 (Conflict) is returned if
the container is not empty.
Response
Code
Name
Description
204
No Content
404
Not Found
409
Conflict
The request could not be completed due to a conflict with the current
state of the resource.
5.2.3.1. Request
This table shows the header parameters for the delete container request:
Name
X-Auth-Token
Type
String
Description
(Required)
This table shows the URI parameters for the delete container request:
Name
Type
Description
{account}
String
{container}
String
Example 5.19. Delete container: HTTP request
DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
5.2.3.2. Response
This table shows the header parameters for the delete container response:
53
Name
May 1, 2015
Type
Content-Length
String
Content-Type
String
Description
(Required) body.
(Required)
X-Trans-Id
API v1
Uuid
(Required)
Date
Datetime
(Required)
Example 5.20. Delete container: HTTP response
Content-Length: 0
X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
Date: Thu, 16 Jan 2014 18:04:04 GMT
54
May 1, 2015
API v1
5.2.4. Create or update container metadata
Method
POST
URI
Description
To set or edit container metadata, perform a POST operation to the container. The operation must include X-Container-Meta-name, where name is the name of your custom metadata. Subsequent POST operations to the header using the same metadata name
overwrite the previous value.
To view your metadata changes, perform a HEAD operation on the container. (For more information, see Show container metadata.) Do not try to send the metadata in your HEAD
request.
Updating container metadata
For containers, the POST request to set metadata does not delete existing
metadata that is not explicitly set in the request.
For example, you use a HEAD request to list container metadata and get the
following results:
X-Container-Meta-Price: 50
X-Container-Meta-Extra: Data
Then you perform a POST request similar to the following example to set metadata on the same container that you listed above:
POST /v1/account/containName HTTP/1.1
X-Auth-Token: yourAuthToken
X-Container-Meta-Cost: 30
Listing the container metadata again after the POST then shows the following
results. The X-Container-Meta-Extra metadata still exists.
X-Container-Meta-Cost: 30
X-Container-Meta-Extra: Data
For information about deleting container metadata, see Create or update container metadata.
Note that updating and deleting object metadata works differently. For an example, see Chapter 7. Additional container services information.
A status code of 204 (No Content) indicates success. Status code 404 (Not Found) is returned when the requested container does not exist.
55
May 1, 2015
API v1
Note
For information about adding metadata for the following purposes, see Get object content and metadata:
• Container quotas
• Access log delivery
Response
Code
Name
Description
204
No Content
404
Not Found
5.2.4.1. Request
This table shows the header parameters for the create or update container metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
String
(Required)
X-Container-Read
String
X-Container-Write
String
X-Remove-Container-name
String
The container metadata. Replace name at the end of the header with
the name of your metadata.
Sets an access control list (ACL) that grants read access. This header
can contain a comma-delimited list of users that can read the contain(Optional) er (allows the GET method for all objects in the container).
Sets an ACL that grants write access. This header can contain a comma-delimited list of users that can write to the container (allows PUT,
(Optional) POST, COPY, and DELETE methods for all objects in the container).
(Optional)
X-Versions-Location
String
X-Remove-Versions-Location
String
Content-Type
String
Removes the metadata item named metadata. For example, X-Remove-Container-Read removes the X-Container-Read metadata item.
to an empty string.
Set to any value to disable versioning.
(Optional)
Changes the MIME type for the object.
(Optional)
X-Detect-Content-Type
Boolean
If set to True, Cloud Files guesses the content type based on the file
extension and ignores the value sent in the Content-Type header, if
(Optional) present.
This table shows the URI parameters for the create or update container metadata request:
Name
Type
Description
{account}
String
{container}
String
56
May 1, 2015
API v1
Example 5.21. Create or update container metadata: HTTP request
POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
X-Container-Meta-Book: MobyDick
X-Container-Meta-Subject: Whaling
5.2.4.2. Response
This table shows the header parameters for the create or update container metadata response:
Name
Type
Content-Length
String
Content-Type
String
(Required) body.
(Required)
X-Trans-Id
Description
Uuid
(Required)
Date
Datetime
(Required)
Example 5.22. Create or update container metadata: HTTP response
Content-Length: 0
X-Trans-Id: tx05dbd434c651429193139-0052d82635
Date: Thu, 16 Jan 2014 18:34:29 GMT
57
May 1, 2015
API v1
5.2.5. Show container metadata
Method
HEAD
URI
Description
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 Create or update container metadata.
If the container exists, a status code of 200 through 299 is returned. If the container does
not exist, a status code of 404 (Not Found) is returned.
Response
Code
Name
Description
204
No Content
404
Not Found
5.2.5.1. Request
This table shows the header parameters for the show container metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
This table shows the URI parameters for the show container metadata request:
Name
Type
Description
{account}
String
{container}
String
Example 5.23. Get container metadata: HTTP request
HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.
1
58
May 1, 2015
API v1
5.2.5.2. Response
This table shows the header parameters for the show container metadata response:
Name
X-Container-Object-Count
Type
Int
Description
The number of objects in the container.
(Required)
X-Container-Bytes-Used
Int
The total number of bytes used for all objects in the container.
(Required)
String
Any metadata set on the container. The name at the end of the header is the name of your metadata. One X-Container-Meta-name re(Required) sponse header appears for each metadata item (for each name).
X-Timestamp
String
X-Container-Read
String
X-Container-Write
String
Content-Length
String
Content-Type
String
container, or object) was modified. The format is the same as a Unix
(Required) timestamp. The storage system uses this header to determine the latest version. For example, during replication, the storage system makes
sure all three object replicas are up to date, and it uses the X-Timestamp header to determine which replica is the latest. You might notice
that objects have both a Last-Modified and X-Timestamp header. The
difference between these two headers is the resolution. Last-Modified
has resolution up to one second, while X-Timestamp has resolution up
to five decimal places of one second.
The access control list (ACL) that grants read access. If not set, this
header is not returned by this operation. This header can contain a
(Optional) comma-delimited list of users that can read the container (allows the
GET method for all objects in the container).
The ACL that grants write access. If not set, this header is not returned
by this operation. This header can contain a comma-delimited list of
(Optional) users that can write to the container (allows PUT, POST, COPY, and
DELETE methods for all objects in the container).
(Required) body.
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
Accept-Ranges
String
The type of ranges accepted.
(Required)
X-Versions-Location
String
to an empty string.
Example 5.24. Get container metadata: HTTP response
Content-Length: 0
X-Timestamp: 1389727543.65372
59
May 1, 2015
X-Container-Meta-Author: SamuelClemens
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
Date: Thu, 16 Jan 2014 18:37:22 GMT
60
API v1
May 1, 2015
API v1
5.2.6. Delete container metadata
Method
POST
URI
Description
To delete a metadata header, use a POST operation. You send the POST operation to the
container with the header X-Remove-Container-Meta-name: value, where name is
the name of the metadata you want to delete and value is any value and is not used.
To set and edit your custom metadata, see Create or update container metadata.
Note that updating and deleting object metadata works differently. For an example, see
Create or update object metadata.
A status code of 200 through 299 indicates success. If the container does not exist, a status
code of 404 (Not Found) is returned.
Response
Code
Name
Description
204
No Content
404
Not Found
5.2.6.1. Request
This table shows the header parameters for the delete container metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
X-Remove-Container-Metaname
String
X-Container-Read
String
X-Container-Write
String
(Required)
The metadata to be deleted. Replace name at the end of the header
with the name for your metadata.
The access control list (ACL) that grants read access. If not set, this
header is not returned by this operation. This header can contain a
(Optional) comma-delimited list of users that can read the container (allows the
GET method for all objects in the container).
The ACL that grants write access. If not set, this header is not returned
by this operation. This header can contain a comma-delimited list of
(Optional) users that can write to the container (allows PUT, POST, COPY, and
DELETE methods for all objects in the container).
This table shows the URI parameters for the delete container metadata request:
Name
{account}
Type
String
Description
61
May 1, 2015
Name
{container}
Type
String
API v1
Description
Example 5.25. Delete container metadata: HTTP request
POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.
1
X-Remove-Container-Meta-Subject: x
5.2.6.2. Response
This table shows the header parameters for the delete container metadata response:
Name
Type
Content-Length
String
Content-Type
String
(Required) body.
(Required)
X-Trans-Id
Description
Uuid
(Required)
Date
Datetime
(Required)
Example 5.26. Delete container metadata: HTTP response
Date: Thu, 09 Jan 2014 22:28:22 GMT
Content-Length: 0
X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1
5.3. Object services
You can perform the operations in the following table on objects in your Cloud Files containers.
• object — for example, MyObject
container names, and object names. For more information, see Section 3.1.2, “Retrieving
the authentication token” [11]. Your authentication token and your account information
are in the service catalog that is produced.
62
Method
May 1, 2015
URI
API v1
Description
GET
PUT
ifest}
DELETE
COPY
HEAD
POST
63
May 1, 2015
API v1
5.3.1. Get object content and metadata
Method
GET
URI
Description
Perform GET operations against an object to retrieve the object's data.
You can perform conditional GET requests by using the following HTTP headers in the request:
•
•
•
•
If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
These headers are documented in http://www.ietf.org/rfc/rfc2616.txt.
You can fetch a portion of the data by using the HTTP Range header. To specify multiple
ranges, separate the range specifications with a comma.
The types of range specifications are as follows:
• Byte range specification: Use a FIRST_BYTE_OFFSET value to specify the start of the
data range, and use a LAST_BYTE_OFFSET value to specify the end of the range. If you
omit the LAST_BYTE_OFFSET value, the offset of the last byte of data is used
• Suffix byte range specification: Use LENGTH bytes to specify the length of the data
range.
The following table shows forms of the header and the ranges of data specified.
Table 5.1. Cloud Files supported range formats
Header
Range of Object Data
Range: bytes=-5
The last five bytes.
Range: bytes=10-15
The six bytes of data after a 10-byte offset.
Range: bytes=10-15,-5
A multipart response that contains the last five bytes
and the six bytes of data after a 10-byte offset. The
Content-Type of the response is then multipart/byteranges.
Range: bytes=4-6
Bytes 4 through 6.
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 multipart response that contains bytes 1 through 3, and
bytes 2 through 5. The Content-Type of the response is
then multipart/byteranges.
Object data is returned in the response body. Object metadata is returned as HTTP headers.
A status code of 200 through 299 indicates success. Status code 404 (Not Found) is returned if the object does not exist.
64
May 1, 2015
API v1
Note
In the following examples that use ranges, the object contains the 10 bytes of
data 0123456789.
Response
Code
Name
Description
200
OK
The request has succeeded. The information returned with the response is dependent on the method used in the request.
404
Not Found
5.3.1.1. Request
This table shows the header parameters for the get object content and metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
This table shows the URI parameters for the get object content and metadata request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
The unique identifier of the object.
This table shows the query parameters for the get object content and metadata request:
Name
signature
Type
String
(Optional)
expires
String
(Optional)
multipart-manifest
Description
Used with temporary URLs to sign the request. For more information
about temporary URLs, see TempURL .
Used with temporary URLs to specify the expiry time of the signature.
For more information about temporary URLs, see TempURL .
String
If you include the multipart-manifest=get query parameter and
the object is a large object, the object contents are not returned. In(Optional) stead, the manifest is returned in the X-Object-Manifest response
header for dynamic large objects or in the response body for static
large objects.
Example 5.27. Get object data: HTTP request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject
HTTP/1.1
Example 5.28. Get object data using a range: HTTP request
HTTP/1.1
65
May 1, 2015
API v1
Range: bytes=4-6
Example 5.29. Get object data using multiple ranges: HTTP request
HTTP/1.1
Range: bytes=1-3,2-5
5.3.1.2. Response
This table shows the header parameters for the get object content and metadata response:
Name
Content-Length
Type
String
Description
The length of the object content in the response body, in bytes.
(Required)
Accept-Ranges
String
The type of ranges that the object accepts.
(Required)
Last-Modified
String
(Required)
ETag
String
Content-Type
String
The date and time that the object was created or the last time that the
metadata was changed.
For objects smaller than 5 GB, this value is the MD5 checksum of the
object content. The value is not quoted. For manifest objects, this val(Required) ue is the MD5 checksum of the concatenated string of MD5 checksums
and ETags for each of the segments in the manifest, and not the MD5
checksum of the content that was downloaded. Also the value is enclosed in double-quote characters. You are strongly recommended to
compute the MD5 checksum of the response body as it is received and
compare this value with the one in the ETag header. If they differ, the
content was corrupted, so retry the operation.
The MIME type of the object.
(Required)
Content-Encoding
String
(Optional)
Content-Disposition
String
X-Delete-At
String
X-Object-Meta-name
String
X-Object-Manifest
String
X-Static-Large-Object
Boolean
If set, the value of the Content-Encoding metadata. If not set, this
header is not returned by this operation.
If set, specifies the override behavior for the browser. For example,
this header might specify that the browser use a download program
(Optional) to save this file rather than show the file, which is the default. If not
set, this header is not returned by this operation.
If set, the time when the object will be deleted by the system in the
format of a UNIX epoch timestamp. If not set, this header is not re(Optional) turned by this operation.
The custom object metadata item, where name is the name of the
metadata item. One X-Object-Meta-name response header ap(Optional) pears for each metadata item (for each name).
If set, to this is a dynamic large object manifest object. The value is the
container and object name prefix of the segment objects in the form
(Optional) container/prefix.
Set to True if this object is a static large object manifest object.
(Optional)
X-Trans-Id
Uuid
66
May 1, 2015
Name
Type
API v1
Description
(Required)
Date
Datetime
(Required)
Example 5.30. Get object data response
HTTP/1.1 200 OK
Date: Wed, 14 Jul 2010 19:37:41 GMT
Last-Modified: Mon, 12 Jun 2010 13:40:18 GMT
ETag: b0dffe8254d152d8fd28f3c5e0404a10
Content-Type: text/html
Content-Length: 512000
[ ...object content... ]
Example 5.31. Get object data using range response
HTTP/1.1 206 Partial Content
Date: Wed, 14 Jul 2010 19:37:41 GMT
Content-Type: application/octet-stream
Content-Range: bytes 4-6/10
Content-Length: 3
456
Example 5.32. Get object data using multiple ranges response
HTTP/1.1 206 Partial Content
Date: Wed, 14 Jul 2010 19:37:41 GMT
Content-Type: multipart/byteranges;boundary=4789b20f24cc4d2a8da2e552e151e6fe
Content-Length: 265
--4789b20f24cc4d2a8da2e552e151e6fe
123
--4789b20f24cc4d2a8da2e552e151e6fe
2345
--4789b20f24cc4d2a8da2e552e151e6fe--
67
May 1, 2015
API v1
5.3.2. Create or update object
Method
PUT
URI
Description
ifest}
Perform PUT operations to write, or overwrite, an object's content and metadata.
Note
The PUT operation actually always creates a new object. If you use this operation on an existing object, you actually replace the existing object and metadata rather than modifying the object. This is why this operation returns a 201
Created status code.
You can ensure end-to-end data integrity by including an MD5 checksum of your object's
data in the ETag header. You are not required to include the ETag header, but we recommend its use to ensure that the storage system successfully stores your object's content.
You can cause an object to expire after a certain date and time by using the X-Delete-At
or X-Delete-After headers during an object PUT operation. The X-Delete-At header requires a Unix epoch timestamp, in integer form. For example, 1348691905 represents
Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific epoch time, you indicate when you want the object to expire, not be served, and be deleted completely from
the storage system. When Cloud Files detects one of these headers, the system automatically stops serving that object at the specified date and time, and shortly after the expiration
date, it removes the object from the storage system.
The HTTP response includes the MD5 checksum of the data written to the storage system.
If you do not send the ETag header in the request, you should compare the value returned
with your content's MD5 locally to perform the end-to-end data validation on the client
side. For manifest objects, ETag is the MD5 checksum of the concatenated string of ETags
for each segment in the manifest, which offers change detection but not direct comparison.
For more information, see Creating large objects.
Note
The best checks for a successful upload are to check the ETag match with a
checksum and to see if you get a 404 (Not Found) status code when you perform a GET, HEAD, POST, or DELETE operation.
You can assign custom metadata to objects by including additional HTTP headers in the
PUT request. To assign custom metadata, use an HTTP header with the X-Object-Metaprefix.
You can also specify the Content-Type header for your object. For example, you can
specify Content-Type: audio/mpeg3 for MP3 files.
A status code of 201 (Created) indicates a successful write. Any status code in the 400
range denotes failure. The 401 (Unauthorized) status code is returned if authentication
68
May 1, 2015
API v1
fails. The 411 (Length Required) status code denotes a missing Content-Length or Content-Type header in the request. If the MD5 checksum of the data written to the storage
system does not match the optionally supplied ETag value, a 422 (Unprocessable Entity)
status code is returned.
No response body is returned.
Response
Code
Name
Description
201
Created
The request has been fulfilled.
202
Accepted
401
Unauthorized
Authentication has failed.
411
Length Required
The request did not specify the length of its content.
422
Unprocessable Entity
The request could not be followed due to semantic errors.
5.3.2.1. Request
This table shows the header parameters for the create or update object request:
Name
X-Auth-Token
Type
String
Description
(Required)
ETag
String
The MD5 checksum of your object's data.
(Optional)
Content-Type
String
The media type of the entity-body sent. If not specified, the Content-Type is guessed, by using the Python mimetypes library, based
(Optional) on the object path.
Content-Length
Int
(Optional)
Content-Disposition
String
(Optional)
Content-Encoding
String
Set to the length of the object content. Do not set if chunked transfer
encoding is being used.
The new browser behavior for the file, so that the downloader can
save the file rather than displaying it using default browser settings.
The underlying media type of the compressed file.
(Optional)
Transfer-Encoding
String
(Optional)
X-Delete-At
Int
(Optional)
X-Delete-After
Int
(Optional)
X-Object-Meta-name
String
(Optional)
Boolean
X-Object-Manifest
String
Set to chunked to enable chunked transfer encoding. If used, do not
set the Content-Length header to a non-zero value.
The certain date, in the format of a Unix epoch timestamp, when the
object will be removed.
The certain date, in the format of a Unix epoch timestamp, after which
the object will be removed.
The custom object metadata. The name at the end of this header represents the name of your metadata.
If you set this header to True, the Content-Type that is sent in the
request (if any) is ignored, and Content-Type is guessed by using
(Optional) the Python mimetypes library based on the object path.
Set to specify that this is a dynamic large object manifest object. The
value is the container and object name prefix of the segment objects
(Optional) in the form container/prefix. You must UTF-8-encode and then URL-
69
Name
May 1, 2015
Type
API v1
Description
encode the names of the container and prefix before you include
them in this header.
X-Copy-From
String
If set, this is the name of an object used to create the new object by
copying the X-Copy-From object. The value is in form contain(Optional) er/object. You must UTF-8-encode and then URL-encode the names
of the container and object before you include them in the header. Using the PUT operation with X-Copy-From has the same effect as using the COPY operation to copy an object.
X-Copy-From-Account
String
Used for account to account copy. Specifies the account name from
which you want to copy an object. (The account name is the last part
(Optional) of the storage URL).
This table shows the URI parameters for the create or update object request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
This table shows the query parameters for the create or update object request:
Name
Type
String
signature
(Optional)
String
expires
(Optional)
multipart-manifest
Description
String
large objects.
Example 5.33. Create or update object request
PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject
HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
X-Delete-At: 1339429105
Content-Disposition: attachment; filename=platmap.mp4
Content-Type: video/mp4
Content-Encoding: gzip
X-Object-Meta-PIN: 1234
5.3.2.2. Response
This table shows the header parameters for the create or update object response:
Name
Content-Length
Type
String
Description
70
Name
May 1, 2015
Type
API v1
Description
(Required)
Etag
String
For objects smaller than 5 GB, this value is the MD5 checksum of the
uploaded object content. The value is not quoted. If you supplied an
(Required) ETag request header and the operation was successful, the values are
the same. If you did not supply an ETag request header, check the
ETag response header value against the object content you have just
uploaded. For static large objects, this value is the MD5 checksum of
the concatenated string of MD5 checksums and ETags for each of the
segments in the manifest, and not the MD5 checksum of the content
that was uploaded. Also the value is enclosed in double-quotes. For
dynamic large objects, the value is the MD5 checksum of the empty
string.
Content-Type
String
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
Example 5.34. Create or update object: HTTP response
Content-Length: 116
Etag: 8a964ee2a5e88be344f36c22562a6486
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
71
May 1, 2015
API v1
5.3.3. Delete object
Method
DELETE
URI
Description
Perform a DELETE operation on an object to permanently remove the object from the storage system (data and metadata).
Object deletion is processed immediately at the time of the request. Any subsequent GET,
HEAD, POST, or DELETE operations return a 404 (Not Found) error unless object versioning
is on and other versions exist. For more information about object versioning, see Object versioning.
Objects with the X-Delete-At or X-Delete-After header assigned are deleted within one day of the expiration time, and the object is not served immediately after the expiration time. For more details, see Expiring objects.
A status code of 204 (No Content) indicates success. Status code 404 (Not Found) is returned when the object does not exist.
For information about bulk deletions, see Bulk delete.
Response
Code
Name
Description
204
No Content
404
Not Found
5.3.3.1. Request
This table shows the header parameters for the delete object request:
Name
X-Auth-Token
Type
String
Description
(Required)
This table shows the URI parameters for the delete object request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
This table shows the query parameters for the delete object request:
72
Name
multipart-manifest
May 1, 2015
Type
API v1
Description
String
large objects.
Example 5.35. Delete object: HTTP request
DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
5.3.3.2. Response
This table shows the header parameters for the delete object response:
Name
Type
Content-Length
String
Content-Type
String
(Required) body.
(Required)
X-Trans-Id
Description
Uuid
(Required)
Date
Datetime
(Required)
Example 5.36. Delete object: HTTP response
Content-Length: 0
X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
Date: Wed, 15 Jan 2014 21:29:16 GMT
73
May 1, 2015
API v1
5.3.4. Copy object
Method
COPY
URI
Description
The new object can be in the same container, but have a different name from the original
object. Or, the new object can have the same or a different name and be located in a different container than the original object.
Note
You can use a PUT operation with the X-Copy-From header to accomplish the
same operation as the COPY operation. The PUT operation always creates a
new object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object.
Suppose you upload a file with the wrong object name or content type, or you need to
move some objects to another container. Without a server-side object copy feature, you
would need to repeat uploading the same content and then delete the existing object.
With a server-side object copy feature, you can save the step of re-uploading the content
and thus also save the associated bandwidth charges, if any were to apply.
You can send a COPY request to the existing object and include the Destination header to specify the destination of the copy. The header value is the container and new object
name in the form of /container/object. Unlike using the PUT request, this approach
does not require a Content-Length header.
Example 5.37. Copy object approach 1 - using COPY
COPY /v1/account/sourceContainer/sourceObject HTTP/1.1
Host: storageURL
Destination: /destinationContainer/destinationObject
Alternatively, you can send a PUT request to the location of the new object (the destination), and add the X-Copy-From header to designate the source of the data. The header value must be the container and object name of the source object in the form of /container/object. The HTTP specification of a PUT request with the X-Copy-From header requires a Content-Length header, but the storage system does not use the Content-Length value to perform the operation. For this reason, you can simply send a
Content-Length value of 0 (zero).
Note
By default, you cannot copy an object larger than 5 GB. For information about
how to handle objects larger than 5 GB, see Authentication.
Example 5.38. Copy object approach 2 - using PUT
PUT /v1/account/destinationContainer/destinationObject HTTP/1.1
74
May 1, 2015
API v1
Host: storageURL
X-Copy-From: /sourceContainer/sourceObject
Content-Length: 0
With both of these approaches, the destination container must exist before you copy the
object.
Note
If you are copying many objects, you can improve the total copy time by issuing several concurrent COPY commands. Because Cloud Files is a distributed
storage system, your concurrent COPY commands run on separate machines simultaneously. As a best practice, you can run up to 100 concurrent COPY commands per container.
If you want to move the object rather than copy it, send a DELETE request to the source
object after copying it. A move is simply a COPY operation followed by a DELETE operation.
All metadata is preserved during the object copy. Note that you can set metadata on the
request to copy the object (with either PUT or COPY), and the metadata overwrites any
conflicting keys on the destination object.
Your account is not charged when you copy or move your objects within the same data
center by using the internal network URI, ServiceNet, as the storage URL. You can find
your ServiceNet endpoint in the service catalog that is created when you authenticate your
session. For information about how to authenticate your session, see Authentication. As
shown in the following partial service catalog example, the ServiceNet URI is listed as internalURL. The name is your Cloud Files storage URL with snet- prepended to it. If you
do not know which data center you are working in, you can find it in the Cloud Control
Panel. (For more information about service access endpoints, see Service access endpoints.)
Example 5.39. 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"
}
]
75
Response
Code
May 1, 2015
Name
API v1
Description
201
Created
The request has been fulfilled.
404
Not Found
5.3.4.1. Request
This table shows the header parameters for the copy object request:
Name
X-Auth-Token
Type
String
Description
(Required)
X-Copy_From
String
(Optional)
Content-Length
Int
(Required)
Destination
String
(Optional)
Destination-Account
String
(Optional)
Content-Type
String
String
Content-Encoding
String
Used with PUT, the container and object name of the source object in
the form of /container/object.
Used with PUT, the content length. Zero (0) is always acceptable for
this operation.
Used with COPY, the container and object name of the destination object in the form of /container/object.
Used for account to account copy. Specifies the destination account
name (which is the last part of the storage URL).
If set, the value of the Content-Encoding metadata.
(Optional)
Content-Disposition
String
(Optional) to save this file rather than show the file, which is the default.
X-Object-Meta-name
String
The container metadata, where name is the name of the metadata
item. You must specify a X-Object-Meta-name header for each
(Optional) metadata item (for each name) that you want to add or update.
This table shows the URI parameters for the copy object request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
Example 5.40. Copy object using COPY: HTTP request
COPY /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MySourceContainer/
MySourceObject HTTP/1.1
Destination: /MyDestinationContainer/MyDestinationObject
76
May 1, 2015
API v1
Example 5.41. Copy object using PUT: HTTP request
PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/
MyDestinationContainer/MyDestinationObject HTTP/1.1
X-Copy-From: /MySourceContainer/MySourceObject
Content-Length: 0
5.3.4.2. Response
This table shows the header parameters for the copy object response:
Name
Content-Length
Type
String
(Required)
Etag
String
(Required)
Content-Type
String
Description
The MD5 checksum of the uploaded object content. The value is not
quoted.
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
X-Copied-From-Last-Modified
String
X-Copied-From
String
(Optional)
(Optional)
Last-Modified
String
(Required)
X-Object-Meta-name
For a copied object, shows the last modified date and time for the container and object name from which the new object was copied.
For a copied object, shows the container and object name from which
the new object was copied. The value is in form container/object.
The date and time that the object was created or the last time that the
metadata was changed.
String
metadata item. One X-Object-Meta-name response header ap(Required) pears for each metadata item (for each name).
Example 5.42. Copy object using COPY: HTTP response
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: MySourceObject
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Object-Meta-Test: testCF
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT
Example 5.43. Copy object using PUT: HTTP response
77
May 1, 2015
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: MySourceObject
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Object-Meta-Test: testCF
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT
78
API v1
May 1, 2015
API v1
5.3.5. Show object metadata
Method
HEAD
URI
Description
Perform a HEAD operation on an object to retrieve object metadata and other standard
HTTP headers.
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 the HEAD return code for
a container. A HEAD request does not return a message body in the response,
so a status code of 200 through 299 indicates success. When a HEAD request is
performed against a container, it queries the container databases, and it does
not retrieve the content from them. Thus, this operation returns the 204 (No
Content) status code. However, when a HEAD request is performed against an
object, it returns a 200 OK status code because it can view the content.
Response
Code
Name
Description
200
OK
404
Not Found
5.3.5.1. Request
This table shows the header parameters for the show object metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
This table shows the URI parameters for the show object metadata request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
This table shows the query parameters for the show object metadata request:
Name
signature
Type
String
(Optional)
Description
79
Name
May 1, 2015
Type
String
expires
(Optional)
API v1
Description
Example 5.44. Get object metadata: HTTP request
HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
5.3.5.2. Response
This table shows the header parameters for the show object metadata response:
Name
Type
X-Timestamp
String
Last-Modified
String
Content-Length
String
Description
container, or object) was modified. The format is the same as a Unix
(Required) timestamp. The storage system uses this header to determine the latest version. For example, during replication, the storage system makes
sure all three object replicas are up to date, and it uses the X-Timestamp header to determine which replica is the latest. You might notice
that objects have both a Last-Modified and X-Timestamp header. The
difference between these two headers is the resolution. Last-Modified
has resolution up to one second, while X-Timestamp has resolution up
to five decimal places of one second.
container, or object) was modified. For Last-Modified, the time zone
(Required) is UTC. You might notice that objects have both a Last-Modified and
X-Timestamp header. The difference between these two headers is
the resolution. Last-Modified has resolution up to one second, while XTimestamp has resolution up to five decimal places of one second.
(Required)
Etag
String
(Required)
Content-Type
String
The MD5 checksum of the uploaded object content. The value is not
quoted.
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
Content-Encoding
String
(Optional)
Content-Disposition
String
X-Delete-At
String
If set, the value of the Content-Encoding metadata. If not set, this
header is not returned by this operation.
(Optional) to save this file rather than show the file, which is the default. If not
set, this header is not returned by this operation.
If set, the time when the object will be deleted by the system in the
format of a UNIX epoch timestamp. If not set, this header is not re(Optional) turned by this operation.
80
Name
May 1, 2015
Type
X-Object-Manifest
String
X-Static-Large-Object
Boolean
API v1
Description
If set, to this is a dynamic large object manifest object. The value is the
container and object name prefix of the segment objects in the form
(Optional) container/prefix.
Set to True if this object is a static large object manifest object.
(Optional)
X-Object-Meta-name
String
metadata item. One X-Object-Meta-name response header ap(Required) pears for each metadata item (for each name).
Example 5.45. Get object metadata: HTTP response
HTTP/1.1 200 OK
Date: Thu, 10 Jun 2010 20:59:39 GMT
Last-Modified: Fri, 11 Jun 2010 13:40:18 GMT
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Type: text/plain; charset=UTF-8
X-Object-Meta-Meat: Bacon
X-Object-Meta-Fruit: Apple
X-Object-Meta-Veggie: Beans
X-Object-Meta-Dairy: Cheese
81
May 1, 2015
API v1
5.3.6. Create or update object metadata
Method
POST
URI
Description
You can set or update your custom metadata for existing objects by sending a POST request to the object name.
Metadata is set by using the header X-Object-Meta-name: value, where name is the
custom name for your metadata and value is the value.
You can also set values for X-Delete-At and X-Delete-After to set expirations for objects.
For information about working with metadata when copying objects, see Copy object.
Deleting object metadata
For objects, the POST request to set metadata deletes all metadata that is not
explicitly set in the request. In other words, ALL the object metadata is set at
the time of the POST request. If you want to edit or remove one header, include all other headers in the POST request and leave out the header that you
want to remove. This means that if you delete one entry without posting the
others, the others will also be deleted at that time.
For example, you use a HEAD request to list object metadata and get the following results:
X-Object-Meta-Price: 50
X-Object-Meta-Extra: Data
Then you perform a POST request similar to the following example to set metadata on the same object that you listed above:
POST /v1/account/containName/objectName HTTP/1.1
X-Object-Meta-Cost: 30
Listing the object metadata again after the POST then shows the following results and X-Object-Meta-Extra no longer exists:
X-Object-Meta-Cost: 30
To remove all metadata for an object, simply perform a POST request for the
object with no metadata specified.
Note that removing container metadata works differently. For more information, see Delete container metadata.
82
May 1, 2015
API v1
A status code of 202 (Accepted) indicates success. Status code 404 (Not Found) is returned
if the requested object does not exist.
This operation does not require a request body and does return a response body.
Response
Code
Name
Description
202
Accepted
The request was accepted for processing.
404
Not Found
5.3.6.1. Request
This table shows the header parameters for the create or update object metadata request:
Name
X-Auth-Token
Type
String
Description
(Required)
X-Object-Meta-name
String
(Optional)
X-Delete-At
Int
(Optional)
X-Delete-After
Int
(Optional)
Content-Type
String
String
Content-Disposition
String
Content-Encoding
String
The container metadata. The name represents the name of your metadata.
The date, in the format of a Unix epoch timestamp, when the object
will be removed.
The date, in the format of a Unix epoch timestamp, after which the
object is removed.
(Optional) to save this file rather than show the file, which is the default.
If set, the value of the Content-Encoding metadata.
(Optional)
This table shows the URI parameters for the create or update object metadata request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
Example 5.46. Update object metadata: HTTP request
POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
X-Object-Meta-Fruit: Apple
83
May 1, 2015
API v1
X-Object-Meta-Veggie: Carrot
5.3.6.2. Response
This table shows the header parameters for the create or update object metadata response:
Name
Content-Length
Type
String
Description
(Required)
Content-Type
String
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
Example 5.47. Update object metadata: HTTP response
HTTP/1.1 202 Accepted
Date: Thu, 07 Jun 2007 20:59:39 GMT
Content-Length: 0
Content-Type: text/plain; charset=UTF-8
X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
84
May 1, 2015
API v1
6. Pseudo hierarchical folders and
directories
Although you cannot nest directories in Cloud Files, you can simulate a hierarchical structure within a single container by adding forward slash characters (/) in the object name. To
navigate the pseudo directory structure, you can use the delimiter query parameter. For
an illustration, see the examples in this section.
Note
In the examples, the objects reside in a container called backups. Within that
container, the objects are organized in a pseudo directory called photos. Remember that the container name is not displayed in the example, but that it is
a part of the object URIs. For example, the URI of the file me.jpg is https://
storage.clouddrive.com/v1/MossoCloudFS_0672d7fa-9f85-4a81a3ab-adb66a880123/backups/photos/me.jpg.
To display a list of all the objects in the storage container, use a GET operation without a
delimiter or prefix parameter.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups
The system returns status code 200 OK and the requested list of objects.
photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg
To limit the displayed results, use the delimiter parameter defined as a forward slash (/),
as shown in the following example.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?delimiter=/
The system returns status code 200 (OK) and the requested matching objects. Because the
request used the slash, only the pseudo directory photos/ is displayed, as shown in the following example. Remember that the returned values from a delimiter query that uses a
slash are not real objects. They have a Content-Type of application/directory and
are in a subdir section of the JSON and XML results.
photos/
To view the objects inside a pseudo directory, including further nested pseudo directories,
use the prefix parameter with the delimiter parameter.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?prefix=
photos/&delimiter=/
The system returns status code 200 (OK) and the objects and pseudo directories within the
top-level pseudo directory, as shown in the following example.
85
May 1, 2015
API v1
photos/animals/
photos/plants/
photos/me.jpg
There is no limit to the number of nested pseudo directories you can create. To navigate
through them, use a longer prefix parameter coupled with the delimiter parameter.
In the following example, the pseudo directory animals contains a pseudo directory called
dogs. To navigate directly to the files contained within dogs, enter the command following.
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/backups?prefix=
photos/animals/dogs/&delimiter=/
The system returns status code 200 (OK) and the following objects and pseudo directories
within the nested pseudo directory.
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
86
May 1, 2015
API v1
7. Additional container services
information
This section provides additional metadata options for containers in Cloud Files.
7.1. Container access control lists
The Cloud Files access control list (ACL) feature allows account owners to specify read or
write access to a particular container for a particular user.
Cloud Files ACLs provide the following metadata headers that you use to define container-level access policies:
• X-Container-Read – This header specifies a comma-delimited list of users that can
read the container (allows the GET method for all objects in the container).
• X-Container-Write – This header specifies a comma-delimited list of users that can
write to the container (allows PUT, POST, COPY, and DELETE methods for all objects in
the container).
Space before or after a comma in the comma-delimited list of users is acceptable. Valid values for these headers are zero to many users.
You can set these headers only on containers, and they apply to all objects within the container.
Note
The account owner does not need to be included as a user in the headers because the account owner always has read and write access to everything in
their Cloud Files account.
However, the users specified in the headers need to have a valid authentication
token for the account to be able to read objects in the container or write to the
container.
You can use the operation to show container metadata to show the absence of the XContainer-Read or X-Container-Write header for an existing container, such as MyContainer in the following example.
Example 7.1. Show container metadata before adding ACL headers: HTTP
request
1
87
May 1, 2015
API v1
Example 7.2. Show container metadata before adding ACL headers: HTTP
response
X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3
Content-Length: 80
Date: Mon, 07 Apr 2014 01:29:22 GMT
Update the existing container to set the X-Container-Read and X-Container-Write
metadata headers to enable read and write access for user1, user2, and user3.
Example 7.3. Update container to add ACL headers: HTTP request
1
X-Container-Read: user1, user2, user3
X-Container-Write: user1, user2, user3
Repeat the operation to show container metadata and confirm the metadata change.
Example 7.4. Show container metadata after adding ACL headers: HTTP
request
1
Example 7.5. Show container metadata after adding ACL headers: HTTP
response
X-Container-Read: user1, user2, user3
X-Container-Write: user1, user2, user3
X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5
Content-Length: 80
Date: Mon, 07 Apr 2014 02:20:12 GMT
For more information about ACLS and using them with RBAC (Section 3.2, “Role Based Access Control” [21]), see the blog post, "Create Cloud Files Container-Level Access Control
Policies".
7.2. Container quotas
Users (most likely account administrators) who have the ability to set container metadata can implement simple quotas on Cloud Files containers. Setting container quotas can
88
May 1, 2015
API v1
be useful for limiting containers for non-admin users, FormPost uploads, or just as a sanity
check. (For information about FormPost, see Section 13.2, “FormPost” [137]).
Any object PUT operations that exceed a quota return a 413 response (request entity too
large) with a descriptive body.
Because the storage system is a true distributed system and because it accepts simultaneous requests, the quotas might not be enforced exactly. For example, if the quota is 5 GB
and two users try to store a 5 GB file at exactly the same time, both operations would be allowed to store the file because at the time of both requests the container had sufficient remaining quota.
Also, for chunked file uploads, the storage system cannot reject transfers that will eventually exceed the quota because the storage system does not know whether the end of the file
will exceed the quota. (For more information about chunked file uploads, see Section 8.1,
“Chunked transfer encoding” [91].
You set quotas by adding metadata to the container. The available metadata values are described in the following table.
Table 7.1. Metadata values for setting container quotas
Metadata header
Description
X-Container-Meta-Quota-Bytes
Maximum size of the container, in bytes
X-Container-Meta-Quota-Count
Maximum number of objects in the container
7.3. Access log delivery
You can use access log delivery to analyze the number of requests for each object, the
client IP address, and time-based usage patterns (such as monthly or seasonal usage).
Access log delivery is set on the container, and every object in the container is tracked. To
enable access logs for a container, set the metadata X-Container-Meta-Access-LogDelivery header to True. If you have multiple containers that you want to track, you
must set the metadata header to TRUE for each container. When your first log is delivered,
the container .ACCESS_LOGS is created. This container holds the access logs for every container for which you turn on logging. Log files exist until you delete them. To turn off logging, set the X-Container-Meta-Access-Log-Delivery header to FALSE.
Log files are named according to the following pattern: container name, log date, log hour,
and MD5 hash. For example:
Media/2012/10/01/16/096e6c4473f235db081deb51f42a8d98.log.gz
In this example, Media is the name of the container, 2012/10/01 is the date (October 1,
2012), and 16 is the hour that the log file was created. There might be multiple files for a
given hour because the storage system splits log files based on both time and log file size.
All times in the access logs are UTC time.
Within the gzip logs, the format of the entries is similar to National Center for Supercomputing Applications (NCSA) combined log format, but without cookies. The pattern follows.
The dashes (-) denote fields that the NCSA combined log format dictates be present but
that Cloud Files does not capture.
89
May 1, 2015
API v1
client_ip - - [day/month/year:hour:minute:second timezone]
“method request HTTP_version” return_code bytes_sent “referrer”
“user_agent”
The following example shows log entries.
Example 7.6. Example access log entries
50.56.228.64 - - [27/08/2012:16:50:22 +0000] "PUT /v1/
MossoCloudFS_bb88c7b9-ea5b-49af-82fc-376ff241963c/CharacterTest_%2521
HTTP/1.0" 401 0 "-" "python-requests/0.13.8
CPython/2.7.3 Linux/3.2.0-29-generic"
50.56.228.64 - - [27/08/2012:16:53:49 +0000] "PUT /v1/
/object_%2521 HTTP/1.0" 201 118 "-" "python-requests/0.13.8
50.56.228.64 - - [27/08/2012:16:53:47 +0000] "PUT /v1/
50.56.228.64 - - [27/08/2012:16:50:36 +0000] "PUT /v1/
90
May 1, 2015
API v1
8. Additional object services information
This sections provides additional information about using objects in Cloud Files.
8.1. Chunked transfer encoding
You can upload data without knowing in advance the amount of data to be uploaded.
You can do this by specifying the HTTP header Transfer-Encoding: chunked and
not using a Content-Length header. A good use of this feature would be performing a
database dump, piping the output to gzip, and then piping the gzip file directly to Cloud
Files without writing the data to disk to compute the file size. If you attempt to upload
more than 5 GB, the server closes the connection and removes the previously sent data
from the system. You must ensure that the data that you transfer is less than 5 GB or split it
into 5 GB chunks, each in its own storage object.
If you have files that are larger than 5 GB and you want to use Cloud Files, you can segment
the files before you upload them, upload them to the same container, and then use a manifest file to allow downloading of a concatenated object that contains all the segmented objects. For more information, see Section 8.2.1, “Creating a dynamic large object” [93].
Example 8.1. Upload unspecified quantity of data: HTTP request
HTTP/1.1
Transfer-Encoding: chunked
X-Object-Meta-PIN: 1234
Example 8.2. Upload unspecified quantity of data response
19
A bunch of data broken up
D
into chunks.
0
8.2. Creating large objects
The content of an object cannot be larger than 5 GB, by default. However, you can store a
larger amount of content by using the following types of objects:
• Segment objects: You divide your content into pieces and upload each piece into its own
object, which is a segment object.
• Manifest objects: You create a manifest object that "points to" the segment objects.
Segment objects do not have any special features and can be created, updated, downloaded, and deleted. However, a manifest object is special—when you download, the system
concatenates the contents of the segment objects and returns the concatenation in the
response body of the request. This behavior extends to the response headers returned by
GET and HEAD operations. The value of the Content-Length header is the total size of
91
May 1, 2015
API v1
all segment objects, and the value of the ETag header is calculated by taking the ETag value of each segment, concatenating them together, and then returning the MD5 checksum
of the result.
Note
If you use a manifest object as the source in a COPY operation, the new object
is a "normal" object (not segmented). If the total size of the source segment objects exceeds 5 GB, the COPY operation fails. However, you can make a duplicate of the manifest object. This new object can be larger than 5 GB.
Following are the types of manifest objects:
• Dynamic large objects: The manifest object has no content. However, it has the X-Object-Manifest metadata header. The value of this header is container/prefix ,
where container is the name of the container where the segment objects are stored
and prefix is a string that all the segment objects have in common.
• Static large objects: The manifest object content is an ordered list of the names of the
segment objects in JSON format.
Although both types of manifest objects have similar behavior, there are differences as explained in the following table.
92
May 1, 2015
API v1
Table 8.1. Comparison of static and dynamic large objects
Feature
Static large object
Dynamic large object
End-to-end integrity
Assured. The list of segments includes
the MD5 checksum (ETag) of each segment. You cannot upload the manifest
object if the ETag in the list differs from
the segment object already uploaded.
If a segment is somehow lost, an attempt to download the manifest object
results in an error.
Not assured. The eventual consistency
model means that although you have
uploaded a segment object, it might
not appear in the container list immediately. If you download the manifest
before the object appears in the container, the object will not be part of
the content returned in response to a
GET request.
Upload order
The segment objects must be uploaded You can upload manifest and segbefore the manifest object.
ment objects in any order. We recommend that you upload the manifest
object after the segments in case a
premature download of the manifest
occurs. However, this is not enforced.
Removal or addition of segment objects
You cannot add or remove segment
objects from the manifest. However,
you can create a completely new manifest object of the same name with a
different manifest list.
Segment object size and number
Segment objects must be at least 1 MB Segment objects can be of any size.
in size, by default. The final segment
object can be any size. By default, a
maximum of 1000 segments are supported.
Segment object container name
The manifest list includes the container All segment objects must be in the
name of each object (that is, segment same container.
objects might be in different containers).
Manifest object metadata
The object has the X-Static-LargeObject metadata header set to True.
You do not set this metadata directly.
Instead the system sets it when you use
a PUT operation on a static manifest
object.
The X-Object-Manifest header
value is container/prefix, indicating where the segment objects are located. You supply this request header
in the PUT operation
Making a copy of the manifest object
To make a copy of the manifest object, include the ?multipartmanifest=get query string with the
COPY operation. The new object contains the same manifest as the original.
The segment objects are not copied. Instead, both the original and new manifest objects share the same set of segment objects.
The COPY operation does not create
a manifest object. To duplicate a manifest object, use the GET operation to
read the value of X-Object-Manifest and use this value in the X-Object-Manifest request header in
a PUT operation. This creates a new
manifest object that shares the same
set of segment objects as the original
manifest object.
You can upload new segment objects or remove existing segments—
the names must simply match the
<prefix> supplied in the X-Object-Manifest header.
8.2.1. Creating a dynamic large object
Objects that are larger than 5 GB must be segmented into smaller segment objects before
you upload them. You then upload the segment objects as you would any other object.
You create a manifest object that tells Cloud Files how to find the segments that make up
the large object. The segments remain individually addressable, but retrieving the manifest
object streams all the segments, concatenated. There is no limit to the number of segments
that can be a part of a single large object. Dynamic large objects rely on the eventual consistency model.
93
May 1, 2015
API v1
Note
In this context, the eventual consistency model means that although you have
uploaded a segment object, it might not appear in the container list immediately. If you download the manifest before the segment object appears in the container, the object will not be part of the content returned in response to a GET
request.
To ensure that the download works correctly, you must upload all the object segments to
the same container and ensure that each object name is prefixed in such a way that the
names sort in the order in which they should be concatenated. You also create and upload
a manifest file. The manifest file is simply a zero-byte file with the extra X-Object-Manifest: container/prefix header, where container is the container that the object
segments are in and prefix is the common prefix for all the segments. The container and
common prefix must be UTF-8 encoded and URL-encoded in the X-Object-Manifest
header.
It is best to upload all the segments first and then create or update the manifest. With this
method, the full object will not be available for downloading until the upload is complete.
Also, you can upload a new set of segments to a second location and then update the manifest to point to this new location. During the upload of the new segments, the original
manifest will still be available to download the first set of segments.
Note
The segments are deletable by the user at any time. If a segment is deleted by
mistake, a dynamic large object, having no way of knowing the segment was
ever there, ignores the deleted file, and the user is returned an incomplete file.
The following examples show how to upload a segment of a large object, the next segment
of a large object, and the manifest.
Example 8.3. Upload a segment of a large object: HTTP request
HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
Example 8.4. Upload a segment of a large object response
s
No response body is returned. A status code of 201 (Created) indicates a successful write.
Status code 411 (Length Required) indicates that the Content-Length header is missing.
If the MD5 checksum calculated by the storage system does not match the optionally supplied ETag value, a 422 (Unprocessable Entity) status code is returned.
You can continue uploading segments as this example shows, prior to uploading the manifest.
94
May 1, 2015
API v1
Example 8.5. Upload the next segment of the large object : HTTP request
HTTP/1.1
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
Example 8.6. Upload the next segment of the large object response
w
Next, upload the manifest that you created that indicates the container in which the object segments reside. Note that uploading additional segments after the manifest is created causes the concatenated object to be that much larger, but you do not need to re-create
the manifest file for subsequent additional segments.
Example 8.7. Upload manifest: HTTP request
HTTP/1.1
Content-Length: 0
X-Object-Manifest: container/prefix/object/segments
Example 8.8. Upload manifest response
[...]
A GET request to the manifest object returns the concatenation of the objects from the
manifest.
When you perform a GET or HEAD request on the manifest, the response's Content-Type is the same as the Content-Type that was set during the PUT request that
created the manifest. You can easily change the Content-Type by reissuing the PUT request.
Note
The ETag in the response for a GET or HEAD on the manifest file is the MD5
sum of the concatenated string of ETags for each of the segments in the manifest. Usually, the ETag is the MD5 sum of the contents of the object, and that
holds true for each segment independently. But it is not meaningful to generate such an ETag for the manifest itself, so this method was chosen to at least
offer change detection.
8.2.2. Creating a static large object
Static large object (SLO) support is similar to dynamic large object (DLO) support because it
enables you to upload many objects concurrently and later download them as a single object. However, unlike dynamic large object support, static large object support does not rely
on the eventual consistency model for the container listings. Instead, static large object support uses a user-defined manifest of the object segments.
95
May 1, 2015
API v1
The benefits of using static large objects are as follows:
• The objects that are uploaded and downloaded can be in different containers, which can
improve performance.
• There is an explicit list of segments, instead of an implied list as with dynamic large objects.
You create a static large object by performing the following steps:
1. Divide your content into pieces and create (upload) a segment object to contain each
piece. You must record the ETag response header returned by the PUT operation. Alternatively, you can calculate the MD5 checksum of the segment prior to uploading
and include this in the ETag request header. Doing so ensures that the upload cannot
corrupt your data. For detailed information, see Section 8.2.2.1, “Uploading the segments” [96].
The maximum number of segment objects per static large object is 1,000. Each segment,
except for the final one, must be at least 1 MB.
2. Create a manifest object by listing the name of each segment object along with its size
and MD5 checksum, in order. You indicate that this is a manifest object by including
the ?multipart-manifest=put query string at the end of the manifest object name.
For detailed information, see Section 8.2.2.2, “Uploading the manifest” [96].
8.2.2.1. Uploading the segments
Upload your segment objects. All the segments, except the last one, need to be larger than
1 MB (1048576 bytes). It might help organizationally to keep them in the same container,
but it is not required. You need the following information about each segment for the next
step, uploading the manifest object:
• path – The container and object name in the following format: containerName/objectName
• etag – The ETag header from the successful 201 response of the PUT operation that uploaded the segment. This is the MD5 checksum of the segment object's data.
• size_bytes – The segment object's size in bytes. This value must 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 use the PUT operation, with the following query parameter at the end of
the manifest object name:
?multipart-manifest=put
The body of the PUT operation is an ordered list of files in JSON data format. The data to
be supplied for each segment is as follows:
• path – The container and object name in the following format: containerName/objectName
96
May 1, 2015
API v1
• etag – The ETag header from the successful 201 response of the PUT operation that uploaded the segment. This is the MD5 checksum of the segment object's data.
• size_bytes – The segment object's size in bytes. This value must match the Content-Length of that object.
Following is an example containing three segment objects. This example illustrates that
in contrast to dynamic large objects, you can use a number of containers and the object
names do not have to conform to a specific pattern.
Example 8.9. Static large object manifest list
[
{
"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 is complete, the Content-Length metadata is set to the total length of all the object segments. A similar situation applies to the ETag header. If it is used in the PUT operation, it must contain the
MD5 checksum of the JSON content. The ETag metadata value is then set to be the MD5
checksum of the concatenated ETag values of the object segments. You can also set the
Content-Type request header and custom object metadata.
When the PUT operation sees the ?multipart-manifest=put query string, it reads
the request body and verifies that each segment object exists and that the sizes and ETags
match. If there is a mismatch, the PUT operation fails.
When you upload the manifest object, the middleware reads every segment passed in and
verifies the size and ETag of each. If any of the objects do not match (for example, an object is not found, the size or ETag is mismatched, or the minimum size is not met), or if everything does match and a manifest object is created, Cloud Files issues a response code.
The response codes are the same as those issued for the create or update object operation
(see Section 5.3.2, “Create or update object” [68]).
When Cloud Files creates the manifest object, Cloud Files sets the X-Static-Large-Object metadata header to True, indicating that this is a static object manifest.
When the manifest object is uploaded, you can be generally assured that every segment in
the manifest exists and that it matches the specifications. However, nothing prevents a user from breaking the static large object download by deleting or replacing a segment that
is referenced in the manifest. Users should use caution when handling the segments.
97
May 1, 2015
API v1
The order of the segments listed in the manifest determines the order in which the segments are concatenated when downloaded. The manifest can reference objects in separate
containers, which improves concurrent upload speed. A single object can be referenced by
multiple manifests.
8.2.2.3. Retrieving a large object
A GET request to the manifest object returns the concatenated content of the segment objects listed in the manifest. If any of the segments from the manifest are not found or their
ETag or Content-Length values no longer match, the GET operation fails and you receive partial results (up to the point of the failure due to not matching). As a result, a 409
(Conflict) status code is logged.
The headers from the GET or HEAD request return metadata for the manifest object as follows:
• Content-Length: The total size of the static large object (the sum of the sizes of the
segments in the manifest)
• X-Static-Large-Object: True
• ETag: The ETag of the static large object (generated the same way as a dynamic large
object)
The GET request with the following query parameter returns the actual manifest file contents:
?multipart-manifest=get
The response body contains generated JSON. The resulting list is not identically formatted like the manifest that you originally used in the PUT operation (?multipart-manifest=put).
The main purpose of the GET or HEAD operation is for debugging.
8.2.2.4. Deleting a large object
A DELETE operation on a manifest object deletes the manifest object itself. The segment
objects are not affected.
A DELETE operation with the following query parameter deletes all segment objects
in the manifest, and then, if all are successfully deleted, the manifest object itself. A
failure response is similar to those for the bulk delete operation (Section 12.2, “Bulk
delete” [131]).
?multipart-manifest=delete
8.2.2.5. Modifying a large object
PUT and POST operations work as follows:
• A PUT operation overwrites the manifest object (and leaves the segments alone).
• A POST operation changes the manifest file's metadata and contents, as with any other
object.
98
May 1, 2015
API v1
8.2.2.6. Listing containers with static large objects
In a list of containers, the size listed for a static large object manifest object is the total size
of the concatenated segments in the manifest, not the size of the manifest file itself. The
overall X-Container-Bytes-Used for the container (and for the account) does not reflect the total size of the manifest, but the actual size of the stored JSON data. This enables
you to see the total size of the static large object in a container list, but does not inflate the
bytes used for the container or the account.
8.3. Enabling file compression
The Content-Encoding header allows a file to be compressed while still preserving the
identity of the underlying media type of the file, for example, a video.
The object must be compressed before it is uploaded. Cloud Files does not perform any automatic compression. The Content-Encoding header enables the client to set the metadata appropriately.
Note
The Rackspace CDN provider, Akamai, encodes HTML, JavaScript, and CSS files
in gzip format. However, in your Cloud Files account, your files are not encoded. For more information, see the blog post Cloud Files CDN Compresses at the
Edge. Compressing these objects helps lower costs and increases download
speeds.
In the following example, the Content-Encoding header indicates the type of encoding
used on the data.
Example 8.10. Content-Encoding: HTTP request
Content-Type: video/mp4
Content-Encoding: gzip
8.4. Enabling bypass of browser behavior
When an object is assigned the Content-Disposition header, you can override a
browser's default behavior for a file so that the browser prompts to save the file rather
than displaying it by using default browser settings.
In the following example, the Content-Disposition header is assigned with an attachment type that indicates how the file should be downloaded.
Example 8.11. Content-Disposition: HTTP request
HTTP/1.1
Content-Type: image/tiff
Content-Disposition: attachment; filename=platmap.tif
99
May 1, 2015
API v1
8.5. Expiring objects
When you perform a PUT or POST operation on an object and assign it either an XDelete-After or X-Delete-At header, the object is scheduled for deletion. This feature is helpful for objects that you do not want to permanently store, such as log files, recurring full backups of a dataset, or documents or images that you know will be outdated
at a future time.
Objects that are assigned the X-Delete-At or X-Delete-After header are deleted
within one day of the expiration time, and the object stops being served immediately after
the expiration time.
The X-Delete-At header requires a UNIX epoch timestamp, in integer form. For example,
1348691905 represents Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific
epoch time, you indicate when you want the object to expire, not be served, and be deleted completely from the storage system.
The X-Delete-After header takes an integer number of seconds that represents the
amount of time from now when you want the object to be deleted. The proxy server that
receives the request converts this header into an X-Delete-At header and calculates the
deletion time using its current time plus the value given in seconds.
To assign expiration headers to existing objects, use the POST operation.
In the following example, the X-Delete-At header is assigned with a UNIX epoch timestamp in integer form for Mon, 11 Jun 2012 15:38:25 GMT. For example timestamps and a
batch converter, go to http://www.epochconverter.com/.
Example 8.12. X-Delete-At: HTTP request
HTTP/1.1
Content-Type: image/jpeg
X-Delete-At: 1339429105
In the following example, the X-Delete-After header is assigned a value in seconds,
equivalent to 10 days. After this time, the object expires.
Example 8.13. X-Delete-After: HTTP request
HTTP/1.1
Content-Type: image/jpeg
X-Delete-After: 864000
8.6. Object versioning
Object versioning enables you to store multiple versions of your content so that you can recover from unintended overwrites and deletions. It provides an easy way to implement version control that can be used on any type of content.
100
May 1, 2015
API v1
We strongly recommends that you put non-current objects in a separate container from the
current versions of objects. After you enable object versioning, new data written to an object causes the last-current version to be written to the separate container. Each of the noncurrent versions has a timestamp appended to it, so you know when it was originally created.
To enable object versioning, you perform the following steps:
1. Create a container where your non-current versions will be written.
2. On the container that holds the current versions of your objects, set the X-Versions-Location metadata header to point to the new non-current version container that you created.
After you complete these steps, versioning is enabled on each object in your current-version
container. Changes to the objects automatically create non-current versions in the separate
container.
Nothing is written to the non-current version container when you initially use a PUT operation to add an object into the current-version container. You create non-current versions
only when you edit existing objects with a PUT request. These non-current versions are labeled according to the following schema:
{length}{objectName}/{time stamp}
Where {length} is the 3-character zero-padded hexadecimal character length of the
{objectName}, and {timestamp} indicates when the object was originally created as a
current version.
Any return status in the 2nn range, such as 202 (Accepted), denotes success. Status codes
in the 4nn or 5nn range denote failure. If you receive an error, you should retry your request. Note, however, that if you specify a container that does not exist as your non-current version container, a status of 412 (Precondition Failed) is returned when you edit the
versioned object. If you receive this error, verify that the container exists.
When object versioning is enabled, requests on objects behave as follows:
• A GET request to a versioned object returns the current version of the object, with no request redirects or metadata lookups required.
• A POST request to a versioned object updates only the current version of the object's
metadata. It does not create a new version of the object. New versions are created when
the content of the object changes.
• A DELETE request to a versioned object removes the current version of the object and replaces it with the most recent non-current version, moving it from the non-current container to the current container. This most recent non-current version carries with it any
metadata last set on it. If you want to completely remove an object and you have five total versions of it, you must perform five DELETE operations on it.
Note
A large-object manifest file cannot be versioned, but it can point to versioned
segments.
101
May 1, 2015
API v1
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
1. Create a version-storing container named versions.
curl -i -XPUT -H "X-Auth-Token: yourAuthToken" http://yourStorageUrl/
versions
2. Create a container named current with a X-Versions-Location header that references versions.
curl -i -XPUT -H "X-Auth-Token: yourAuthToken" \
-H "X-Versions-Location: versions" http://yourStorageUrl/current
3. Create an object (the first version).
curl -i -XPUT --data-binary 1 -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl/current/myobject
4. 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 list of the older versions of the object. (The example includes the hexadecimal
number for the length of the file name.)
curl -i -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl/versions?prefix=008myobject/
6. Delete the current version of the object and see that the older version is no longer in the
versions container.
curl -i -XDELETE -H "X-Auth-Token: yourAuthToken" \
http://yourStorageUrl>/current/myobject
curl -i -H "X-Auth-Token: yourAuthToken " \
http://yourStorageUrl/versions?prefix=008myobject/
8.7. Account to account copy
The account to account copy capability adds the ability to copy objects between different
accounts on the server.
To use this capability to read from or write to the accounts, you must have a access to the
containers. You can use a container access control list (ACL) to control access to a container
and its objects. For more information about ACLs, see Section 7.1, “Container access control
lists” [87].
Use the following operations and headers to perform an account to account copy:
• A COPY command with the following headers:
• Destination-Account: Specifies the account name (which corresponds to the last
part of the storage URL).
102
May 1, 2015
API v1
• Destination: Used with COPY, specifies the container and object name of the destination object in the form of /container/object.
For more information about the COPY command, see Copy object.
• A PUT command with the following headers:
• X-Copy-From-Account: Specifies the account name (which corresponds to the last
part of storage URL).
• X-Copy-From: Used with PUT, specifies the container and object name of the source
object in the form of /container/object.
For more information about the PUT command, see Create or update object.
Note
If your storage URL is https://storage101.dfw1.clouddrive.com/
v1/ MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,
your account name is MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee.
Use the following examples to complete the steps to use account to account copy.
COPY command steps
1. Use the POST command to set X-Container-Write metadata on the destination container.
Request:
POST /v1/Destination_Account/Destination_Container HTTP/1.1
X-Auth-Token: Destination_User_Auth_Token
X-Container-Write: Source_User_Name
Response:
204 No Content
Content-Length: 0
X-Trans-Id: tx1abc1d6005134be99b1db-0054da619adev1
Date: Tue, 10 Feb 2015 19:52:58 GMT
2. Use the COPY command to copy the object.
Request:
COPY /v1/Source_Account/Source_Destination/Source_Object HTTP/1.1
X-Auth-Token: Source_User_Auth_Token
Destination: Destination_Container/Destination_Object
Destination-Account: Destination_User_Account
(such as,
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee)
Response:
103
May 1, 2015
API v1
201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Tue, 13 Jan 2015 20:53:09 GMT
X-Copied-From: copy_test/new_copy_object.txt
Last-Modified: Tue, 10 Feb 2015 19:59:49 GMT
Etag: c6995201745ed71f24ba352750bde444
X-Copied-From-Account: StagingUS_xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb
X-Trans-Id: txd819a3f557de449cb0879-0054da6334dev1
Date: Tue, 10 Feb 2015 19:59:48 GMT
PUT command steps
1. Use the POST command to set X-Container-Write metadata on destination container.
Request:
POST /v1/Destination_Account/Destination_Container HTTP/1.1
X-Auth-Token: Destination_User_Auth_Token
X-Container-Write: Source_User_Name
Response:
204 No Content
Content-Length: 0
X-Trans-Id: tx0f6c102033564bb0800e3-0054da677fdev1
Date: Tue, 10 Feb 2015 20:18:07 GMT
2. Use the PUT command to copy the object.
Request:
PUT /v1/Destination_Account/Dest_Container/Dest_Object HTTP/1.1
X-Auth-Token: Source_User_Auth_Token
X-Copy-From: /source_container/source_object
X-Copy-From-Account: Source_User_Account
(such as, MossoCloudFS_aaaaaaaabbbb-cccc-dddd-eeeeeeeeeeee)
Content-Length: 0
(the actual value is ignored)
Response:
201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Tue, 10 Feb 2015 20:46:32 GMT
X-Copied-From: source/source_object.txt
Last-Modified: Tue, 10 Feb 2015 21:14:50 GMT
Etag: d41d8cd98f00b204e9800998ecf8427e
X-Copied-From-Account: StagingUS_xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb
X-Trans-Id: txe3373a175f944020a63d9-0054da74c9dev1
Date: Tue, 10 Feb 2015 21:14:49 GMT
104
May 1, 2015
API v1
9. API operations for CDN services
This chapter provides further description for several of the API operations described in
Chapter 5, “API operations for storage services” [30]. These API operations have a specific
purpose for the content delivery network (CDN) service that is available in Cloud Files.
You direct the REST API methods described in this chapter to the endpoints listed in the
cloudFilesCDN section of the service catalog that you obtain during successful authentication. (For more information, see Section 3.1, “Authentication” [11] and Section 3.3, “Service access endpoints” [22].)
A CDN-enabled container is a public container that is served by the Akamai content delivery
network. The files in a CDN-enabled container are publicly accessible and do not require an
authentication token for read access. However, uploading content into a CDN-enabled container is a secure operation and does require a valid authentication token. (Private containers are not CDN-enabled and the files in a private container are not publicly accessible.)
The following sections describe the operations that you can perform within the storage system:
• Section 9.1, “CDN account services” [105] describes operations that you can perform at
the account level for Cloud Files CDN services.
• Section 9.2, “CDN container services” [108] describes operations that you can perform
on containers.
• Section 9.3, “CDN object services” [117] describes operations that you can perform on
objects.
Method
URI
Description
CDN account services
GET
end_marker,format}
Lists CDN-enabled containers sorted by name.
CDN container services
PUT
HEAD
/v1/{account}/{container}{?format} Gets a CDN-enabled container's metadata.
POST
Enables or disables a container for use with the CDN.
Updates the CDN-enabled container's metadata.
CDN object services
DELETE
/v1/{account}/{container}/{object} Deletes CDN-enabled objects.
9.1. CDN account services
You can perform the operation in the following table at the account level of your Cloud
Files CDN account.
105
May 1, 2015
API v1
For your own requests, you must use your own account information and authentication token. For more information, see Section 3.1.2, “Retrieving the authentication token” [11].
Your authentication token and your account information are in the service catalog that is
produced.
Method
GET
URI
Description
end_marker,format}
106
May 1, 2015
API v1
9.1.1. List CDN-enabled containers
Method
GET
URI
Description
end_marker,format}
GET operations against the cloudFilesCDN endpoints for an account retrieve a list of
CDN-enabled containers. No private containers appear in the list. (For the CDN endpoints,
see "Service access endpoints".)
This operation does not require a request body. A list of CDN-enabled containers is returned in the response body, one container name per line.
An HTTP response status code of 200 through 299 indicates success. A 200 (OK) code is returned if there are containers, and a 204 (No Content) code is returned if there are no containers.
To view the CDN container details, see List metadata for CDN-enabled container.
Response
Code
Name
Description
200
OK
404
Not Found
9.1.1.1. Request
This table shows the URI parameters for the list cdn-enabled containers request:
Name
Type
String
{account}
Description
This table shows the query parameters for the list cdn-enabled containers request:
Name
limit
Type
Int
Description
For an integer value n, limits the number of results to n values.
(Optional)
marker
String
Given a string value x, returns container names greater in value than
the specified marker. Only strings using UTF-8 encoding are valid. Us(Optional) ing marker provides a mechanism for iterating through the entire list
of containers.
end_marker
String
(Optional)
format
String
Given a string value x, returns container names lesser in value than the
specified end marker. Only strings using UTF-8 encoding are valid.
Value of the serialized response format, either JSON or XML.
(Optional)
Example 9.1. List CDN-enabled containers: HTTP request
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123 HTTP/1.1
107
May 1, 2015
API v1
Host: cdn.clouddrive.com
Example 9.2. List CDN-enabled containers: HTTP request with a query
parameter ?format=json
GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=json HTTP/1.1
9.1.1.2. Response
Example 9.3. List CDN-enabled containers: HTTP response
HTTP/1.1 200 OK
Date: Thu, 08 Sep 2011 14:35:45 GMT
Content-Type: text/plain
images
movies
Example 9.4. List CDN-enabled containers: HTTP response using a query
parameter ?format=json
HTTP/1.1 200 OK
X-Trans-Id: tx82a6752e00424edb9c46fa2573132e2ciad3
Date: Tue, 05 May 2015 14:09:02 GMT
[
{
"cdn_enabled": true,
"cdn_ios_uri": "http://acc3b9ba6a79805f5577e7e60117100ffd73b45850c0b1fd96c1.iosr.cf5.rackcdn.com",
"cdn_ssl_uri": "https://
83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1. ssl.cf0.rackcdn.com",
"cdn_streaming_uri": "http://
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.stream.cf0.rackcdn.
com",
"cdn_uri": "http://
081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.cf0.rackcdn.com",
"log_retention": false,
"name": "cdn_test",
"ttl": 259200
},
...
]
9.2. CDN container services
You can perform the operations in the following table on CDN-enabled containers in your
Cloud Files account.
When you CDN-enable a container, all the objects within it become available on the CDN.
Similarly, after a container is CDN-enabled, any objects added to it through the storage
108
May 1, 2015
API v1
service become CDN-enabled. After you CDN-enable a container, its publicly-available URI
can be found with the header X-Cdn-Uri, and its objects can be accessed with X-CdnUri/objectName. By knowing this pattern, you can pre-generate the URI for an object
before it is added to the container.
When you enable a container in the CDN service, you automatically generate URIs for SSL
and streaming usage. They are listed under the X-Cdn-Ssl-Uri and X-Cdn-Streaming-Uri headers.
On August 13, 2012, the format of new CDN URIs changed in order to enhance
the security of the CDN. Any URIs set in the older format (for example, http://
c25810.r10.cf1.rackcdn.com/mydog.jpg) continue to work. However, any
newly generated CDN URIs have the new format, as shown in the following example:
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com/mydog.jpg.
Note on CDN charges
Monitor your CDN charges. When you CDN-enable a container, not only can
anyone view it, but anyone can link to it. We recommend that you monitor
your bandwidth usage and charges in the Cloud Control Panel so that you
know if someone is hot-linking your content. For instructions about viewing
your usage charges, see the Knowledge Center article "Protect your Cloud Files
CDN Bill from Unexpected Usage".
and container names. For more information, see Section 3.1.2, “Retrieving the authentication token” [11]. Your authentication token and your account information are in the service catalog that is produced.
Method
URI
Description
PUT
HEAD
POST
109
May 1, 2015
API v1
9.2.1. CDN-enable and CDN-disable a container
Method
PUT
URI
Description
Before a container can be CDN-enabled, it must exist in the storage system. To CDN-enable
the container, perform a PUT request against it using the publicURL noted in the service catalog for Cloud Files during authentication, and set the X-CDN-Enabled header to
True.
Retrieving the authentication token provides an example of the information in the service
catalog for cloudfilesCDN.
When a container is CDN-enabled, any objects stored in it are publicly accessible over the
CDN 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 as the endpoint for operations against the CDN management service, but you should use whatever
endpoints your authentication request provides. For more information about
service access endpoints, see "Service access endpoints".
Any CDN-accessed objects are cached in the CDN for a specified amount of time, called the
Time To Live (TTL). Each time the object is accessed after the TTL expires, the CDN refetches
and caches the object for the next TTL period.
You can specify the TTL for an object by including the X-Ttl: integerSeconds header. Setting the TTL is the same as setting the Expires and Cache-Control headers for
the cached object. The minimum TTL is 15 minutes (900 seconds), the maximum TTL is 1
year (31536000 seconds), and the default TTL is 72 hours (259200 seconds). However, setting a TTL for a long time does not guarantee that the content stays populated on CDN
edge servers for the entire period. The most popular objects stay cached based on the edge
location's logic.
A status code of 201 (Created) indicates that the container was CDN-enabled as requested.
If the container is already CDN-enabled, a 202 (Accepted) status code is returned, and the
TTL is adjusted. A status code of 204 (No Content) indicates that the container was CDN-enabled as requested but has no content.
To remove the container from the CDN, change the X-Cdn-Enabled header to False.
However, note that objects remain on the CDN edge server and are served to the public until their TTL expires.
Note
The CDN URI is unique per container. After the container is CDN-enabled, you
can make a HEAD request to the Cloud Files CDN endpoint with the container
110
May 1, 2015
API v1
name to return the CDN URI in the X-Cdn-Uri header. You can use a cURL request similar to the following example:
curl -I -H 'x-auth-token: yourAuthToken'
cloudFilesCDN:yourPublicURL/yourContainerName
Response
Code
Name
Description
200
OK
202
Accepted
204
No Content
404
Not Found
9.2.1.1. Request
This table shows the header parameters for the cdn-enable and cdn-disable a container request:
Name
Type
X-Ttl
Int
X-Cdn-Enabled
String
Description
Specifies the Time To Live (TTL) in seconds for an object to be cached
in the CDN. The default value is 259200 seconds, or 72 hours. The min(Optional) imum TTL is 15 minutes (or 900 seconds), and the maximum is 1 year
(31536000 seconds).
Indicates if a container is CDN-enabled. Valid values are True and False.
(Optional)
This table shows the URI parameters for the cdn-enable and cdn-disable a container request:
Name
Type
Description
{account}
String
{container}
String
Example 9.5. CDN-enable container: HTTP request
PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
X-Ttl: 259200
X-Cdn-Enabled: True
Example 9.6. CDN-disable container: HTTP request
1
X-CDN-Enabled: False
111
May 1, 2015
API v1
9.2.1.2. Response
This table shows the header parameters for the cdn-enable and cdn-disable a container response:
Name
Content-Length
Type
String
(Required)
Content-Type
String
(Required)
Date
Datetime
Description
(Required)
X-Cdn-Ios-Uri
String
(Required)
X-Cdn-Ssl-Uri
String
X-Cdn-Streaming-Uri
String
The URI for downloading the object over HTTPS, using SSL. (The user
cannot have custom SSL certificates because the Rackspace CDN part(Required) ner does not provide that feature.)
(Required)
X-Cdn-Uri
String
(Required)
X-Trans-Id
The URI for video streaming that uses HTTP Live Streaming from Apple.
Uuid
The URI for video streaming that uses HTTP Dynamic Streaming from
Adobe.
Indicates the URI that you can combine with object names to serve objects through the CDN.
(Required)
Example 9.7. CDN-enable container: HTTP response
Content-Length: 0
Content-Type #text/html; charset=UTF-8
Date #Wed, 17 Dec 2014 19:58:49 GMT
X-Cdn-Ios-Uri #http://acc3b9ba6a79805f5577-e7e60117100ffd73b45850c0b1fd96c1.
iosr.cf5.rackcdn.com
X-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.
ssl.cf0.rackcdn.com
X-Cdn-Streaming-Uri: http://
com
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.
cf0.rackcdn.com
X-Trans-Id: tx82a6752e00424edb9c46fa2573132e2c
112
May 1, 2015
API v1
9.2.2. List metadata for CDN-enabled container
Method
HEAD
URI
Description
You can view CDN-enabled container details by performing a HEAD operation on a container where the Host header value is one of the cdnCloudFiles service access endpoints.
(For the CDN endpoints, see Service access endpoints.)
If the container is (or ever has been) CDN-enabled, the metadata is returned in headers in
the response for plain text, or in the response body for XML or JSON, if you request either
as your output format.
Note
Remember that your HEAD operation must be on the CDN host (for example,
cdn.clouddrive.com). Otherwise, you will see the metadata for your private container as described in Get account metadata.
A 204 (No Content) HTTP status code is returned if the account has no containers. Otherwise, the status code of 200 (OK) is returned. Status code 404 (Not Found) is returned if the
requested container was not found.
Response
Code
Name
Description
200
OK
204
No Content
404
Not Found
9.2.2.1. Request
This table shows the URI parameters for the list metadata for cdn-enabled container request:
Name
Type
Description
{account}
String
{container}
String
This table shows the query parameters for the list metadata for cdn-enabled container request:
Name
format
Type
String
(Optional)
Description
The optional format for the returned information, either XML or
JSON.
113
May 1, 2015
API v1
Example 9.8. List metadata for CDN-enabled container: HTTP request
1
Example 9.9. List metadata for CDN-enabled container: JSON request
HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=
json
Example 9.10. List metadata for CDN-enabled container: XML request
HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?format=
xml
9.2.2.2. Response
This table shows the header parameters for the list metadata for cdn-enabled container response:
Name
Type
X-Cdn-Uri
String
X-Ttl
Int
X-Cdn-Enabled
Boolean
The URI for downloading the object over HTTP. This URI can be combined with any object name within the container to form the publicly
(Required) accessible URI for that object for distribution over a CDN system.
The TTL value in seconds. The default value is 259200 seconds, or 72
hours. The minimum TTL is 15 minutes (or 900 seconds), and the maxi(Required) mum is 1 year (31536000 seconds).
(Required)
X-Log-Retention
Boolean
(Required)
X-Cdn-Ssl-Uri
String
X-Cdn-Streaming-Uri
String
True or False to indicate whether the container is currently marked to
allow public serving of objects through the CDN.
True or False to indicate whether the CDN access logs should be collected and stored in the Cloud Files storage system.
The URI for downloading the object over HTTPS, using SSL. (The user
cannot have custom SSL certificates because the Rackspace CDN part(Required) ner does not provide that feature.
(Required)
X-Cdn-Ios-Uri
Description
String
(Required)
The URI for video streaming that uses HTTP Dynamic Streaming from
Adobe.
The URI for video streaming that uses HTTP Live Streaming from Apple.
Example 9.11. Get CDN-enabled container metadata: HTTP request
X-Cdn-Ssl-Uri: https://
83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.
ssl.cf0.rackcdn.com
X-Ttl: 259200
114
May 1, 2015
API v1
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.
r49.cf0.rackcdn.com
X-Cdn-Enabled: True
X-Log-Retention: False
X-Cdn-Streaming-Uri: http://084cc2790632ccee0a12-346eb45fd42c58ca13011d
659bfc1ac1.r49.stream.cf0.rackcdn.com
Content-Length: 0
Example 9.12. List metadata for CDN-enabled container: JSON response
HTTP/1.1 200 OK
Date: Tue, 30 Oct 2012 14:41:29 GMT
Content-Length: 127
[
{"name":"test_container",
"cdn_enabled":"true",
"ttl":28800,
"log_retention":"true",
"cdn_uri":"http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.
r10.cf1.rackcdn.com",
"cdn_ssl_uri":"https://
83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.ssl.stg2.rackcdn.com",
"cdn_streaming_uri":"http://
80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.rackcdn.com"}
]
Example 9.13. List metadata for CDN-enabled container: XML response
HTTP/1.1 200 OK
Date: Tue, 30 Oct 2012 17:57:28 GMT
Content-Length: 267
<account name="WidgetsRUs.button">
<container>
<name>images</name>
<cdn_enabled>True</cdn_enabled>
<ttl>86400</ttl>
<log_retention>True</log_retention>
<cdn_url>
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.
cf1.rackcdn.com
</cdn_url>
<cdn_ssl_url>
https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.ssl.
stg2.rackcdn.com
</cdn_ssl_url>
<cdn_streaming_url>
http://084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1. r49.
stream.cf0.rackcdn.com
</cdn_streaming_url>
</container>
</account>
115
May 1, 2015
API v1
9.2.3. Update CDN-enabled container metadata
Method
POST
URI
Description
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) is returned if the requested container is not found.
Response
Code
Name
Description
204
No Content
The server fulfilled the request but does not need to return a body.
404
Not Found
9.2.3.1. Request
This table shows the header parameters for the update cdn-enabled container metadata request:
Name
Type
X-Log-Retention
Boolean
(Optional)
X-Cdn-Enabled
Boolean
X-Ttl
Int
Description
True or False to indicate whether the CDN access logs should be collected and stored in the Cloud Files storage system.
True or False to enable or disable public sharing over the CDN. If
you have content currently cached in the CDN, setting your container
(Optional) back to private does not purge the CDN cache. You have to wait for
the TTL to expire or purge the objects.
The TTL value in seconds. The default value is 259200 seconds, or 72
hours. The minimum TTL is 15 minutes (or 900 seconds), and the maxi(Optional) mum is 1 year (31536000 seconds).
This table shows the URI parameters for the update cdn-enabled container metadata request:
Name
Type
Description
{account}
String
{container}
String
Example 9.14. Update CDN-enabled container metadata: HTTP request
1
116
May 1, 2015
API v1
X-Ttl: 86400
X-Cdn-Enabled: True
X-Log-Retention: True
9.2.3.2. Response
Example 9.15. Update CDN-enabled container metadata: HTTP response
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.
cf0.rackcdn.com
X-Cdn-Enabled: True
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.r49.stream.cf0.rackcdn.
com
Content-Length: 0
9.3. CDN object services
You can perform the operation in the following table on objects in your Cloud Files CDN-enabled containers.
• object — for example, MyObject
container names, and object names. For more information, see Section 3.1.2, “Retrieving
the authentication token” [11]. Your authentication token and your account information
are in the service catalog that is produced.
Warning
You request this operation against a CDN management services URI, such as
https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee/, as shown in Table 3.4, “Regionalized service
endpoints for CDN management services” [24]. If you use a Storage management services URI by mistake, you delete your object.
Method
DELETE
URI
Description
117
May 1, 2015
API v1
9.3.1. Delete CDN-enabled object
Method
DELETE
URI
Description
When you find it necessary to remove a CDN-enabled object from public access before the
TTL expires, you can perform a DELETE operation against the object, or you can create a
support ticket to purge the entire container.
Warning
You request this operation against a CDN management services URI, such as
https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee /, as shown in Table 3.4. Regionalized service
endpoints for CDN management services. If you use a Storage management services URI by mistake, you delete your object.
Note
You should limit object purges to situations in which serious personal, business,
or security consequences could occur if the object remained publicly accessible
on the CDN (for example, when someone publishes your company's quarterly
earnings too early).
You can purge objects from the CDN in the following ways:
• By using DELETE in the API
You can manually purge CDN-enabled objects without having to wait for the TTL to expire, and you can optionally be notified by email that the object has been purged.
You can use the DELETE operation against a maximum of 25 objects per day using the
API.
An attempt to delete more objects results in a 498 (Rate Limited) status code.
Here is an example response for hitting the purge rate limit:
$ curl -i -XDELETE -H'x-auth-token: f064c46a782c444cb4ba4b6434288f7c'
https://cdn1.clouddrive.com/v1/MossoCloudFS_0672d7fa-9f85-4a81-a3abadb66a880123/MyContainter/MyObject
HTTP/1.1 498 Rate Limited
Content-Length: 42
X-Trans-Id: txb63f31d26bf84c058542b-0055101cd0dfw1
Date: Mon, 23 Mar 2015 14:01:52 GMT
• By creating a support ticket to purge an entire container
The 25-object limit does not apply when purging an entire container through Support.
118
May 1, 2015
API v1
Note
To prevent the container from going back to the CDN, first change the X-CDNEnabled flag to False as shown in CDN-enable and CDN-disable a container.
The system purges the object from the CDN and sends an email to the indicated address or
addresses. If you want to notify more than one person about the deletion, you can enter a
comma-separated list of addresses. The email address is optional.
A status code of 204 (No Content) indicates success. Status code 498 (Rate Limited) indicates that the account has reached its 25 object daily purge limit for CDN-enabled objects.
Status code 403 (Forbidden) indicates that an authorization problem occurred.
Because there are so many edge servers around the world, purging objects might take a
long time. Be patient while waiting for a response.
Response
Code
Name
Description
204
No Content
The server fulfilled the request but does not need to return a body.
403
Forbidden
The server refused to respond to request.
498
Rate Limited
The account has reached the 25 object daily purge limit for CDN-enabled objects.
9.3.1.1. Request
This table shows the URI parameters for the delete cdn-enabled object request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
Example 9.16. Delete CDN-enabled object: HTTP request
DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/
MyObject HTTP/1.1
Host: cdn2.clouddrive.com
X-Purge-Email: [email protected], [email protected]
9.3.1.2. Response
Example 9.17. Delete CDN-enabled object: HTTP response
Content-Length: 0
119
May 1, 2015
X-Trans-Id: txd57d75dcd51e4a79a886d-0055101ecford1
Date: Mon, 23 Mar 2015 14:10:25 GMT
120
API v1
May 1, 2015
API v1
10. Additional CDN services information
The chapter provides additional information about working with the Cloud Files CDN services.
10.1. Purge CDN-enabled containers
For a container to be purged from the CDN, you can either wait for the TTL to expire, or
you can request that Rackspace remove, or purge, a CDN-enabled container from the network. After you have made the request to Rackspace through a support ticket, the system
purges the container from the CDN, and sends an email to the address (or multiple addresses) that you indicate through the ticket. The email address notification is optional.
Note
To prevent the container from going back to the CDN, first change the X-CDNEnabled flag to False as shown in the section about CDN-enabling and disabling a container in Chapter 9, “API operations for CDN services” [105].
10.2. CDN-enabled containers served through SSL
A HEAD operation for a CDN-enabled container returns an SSL URI, X-Cdn-Ssl-Uri, in
addition to the other headers associated with CDN. This feature enables you to use HTTPS
protocol in URIs that are used for requesting objects stored in CDN-enabled containers.
Example 10.1. CDN-enabled container metadata: HTTP request
1
Example 10.2. CDN-enabled container metadata with SSL URI: HTTP response
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.
cf0.rackcdn.com
X-Cdn-Enabled: True
com
Content-Length: 0
10.3. Streaming CDN-enabled containers
In addition to the other headers associated with CDN, a HEAD operation against a CDN-enabled container returns the following streaming URIs to enable the streaming feature:
121
May 1, 2015
API v1
• X-Cdn-Streaming-Uri, which specifies a URI for video streaming that uses HTTP Dynamic Streaming from Adobe
• X-Cdn-Ios-Uri, which specifies the URI for video streaming that uses HTTP Live
Streaming from Apple
Streaming is a method of relaying data, such as video and audio material, over the network
as a steady continuous stream, allowing playback to proceed while subsequent data is being received.
For information about streaming to iOS devices, see Section 10.4, “iOS streaming” [122].
Example 10.3. CDN-enabled container metadata: HTTP request
1
Example 10.4. CDN-enabled container metadata with streaming URIs: HTTP
response
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Ios-Uri: http://fb1ca9de5ff9525ff6f8-64e65126753c56b595824f56d25789bb.
iosr.cf1.rackcdn.com
com
X-Cdn-Enabled: True
X-Cdn-Ssl-Uri: https://2cb7edde3eac1dd66ea4-64e65126753c56b595824f56d25789bb.
ssl.cf1.rackcdn.com
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1. r49.
cf0.rackcdn.co
Content-Length: 0
10.4. iOS streaming
The Cloud Files CDN allows you to stream video to iOS devices without needing to convert
your video. After you CDN-enable your container, you have the tools necessary for streaming media to multiple devices. To leverage this ability, you must check the client's user agent
with JavaScript. An example of the user agent check and how to use it follows.
1. CDN-enable your container. For instructions, see the section about CDN-enabling a container in Chapter 9: “API operations for CDN services”. Two streaming URIs are created:
the container's streaming URI (X-Cdn-Streaming-Uri) and its iOS streaming URI (XCdn-Ios-Uri).
2. Perform a HEAD request against the CDN-enabled container to view these URIs.
3. Link to your content in a HTML page by using a <video> element.
122
May 1, 2015
API v1
4. Set the SRC attribute of the <video> element to the full streaming URI for your container plus the name of your content. In the following 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>
5. Add JavaScript to the <head> element of your HTML page to check if the user agent
is an iOS device. If it is, the JavaScript should use the container's iOS streaming URI (XCdn-Ios-Uri) instead of the regular streaming URI. The Cloud Files CDN delivers the
properly formatted content for iOS devices only when the iOS streaming URI is used. In
the following example, the JavaScript sets the <src> attribute of the <video> element
videotag to the iOS Streaming URI. Remember to add your content's name to the end
of the iOS streaming URI.
Example 10.6. JavaScript for user agent check
<script type=”text/javascript”>
function isIOS(){
return ((navigator.userAgent.match(/iPhone/i)) ||(navigator.
userAgent.match(/iPod/i)) || (navigator.userAgent.match(/iPad/
i))) != null;
}
function init(){
if (isIOS()){
document.getElementById(“videotag”).src = “http://
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.
iosr.cf0.rackcdn.com/MobyDick.mp4”;
}
}
</script>
6. Add init() to the <body> element of your HTML page to call the user agent check
when the page loads, as shown in the following example.
Example 10.7. Load JavaScript in HTML page
<body onload=”init()”>
With these pieces of code in place, the proper content streams are set for iOS devices.
10.5. CDN log delivery
If you set the X-Log-Retention header on your CDN-enabled container to True, you enable CDN log delivery on that container. Then all the request logs generated by the edge
nodes of the CDN provider to objects in this container are delivered into a special container created in your account named .CDN_ACCESS_LOGS. The delivered logs are in the same
format as access logs (see Section 7.3, “Access log delivery” [89]). These logs, once deliv123
May 1, 2015
API v1
ered, are treated like any other object in your account, and you are charged for that storage.
You can use the CDN logs to analyze the number of requests for each object, the client IP
address, and time-based usage patterns (such as monthly or seasonal usage).
Note
Delivery times vary greatly for CDN logs. In most cases, the logs are delivered
within several hours, but delivery can sometimes take days. Cloud Files can only
deliver the logs to you as fast as the logs are delivered from the CDN provider.
When you set the X-Log-Retention header to True on a CDN-enabled container, Cloud
Files tracks every object in the container. If you have multiple containers that you want to
track, you must set the X-Log-Retention header to TRUE for each container. When your
first log is delivered, Cloud Files creates the .CDN_ACCESS_LOGS container. This container holds the CDN logs for every container for which you turn on logging. Log files exist until
you delete them. To turn off logging, set the X-Log-Retention header to FALSE.
Log files are named according to the following pattern: container name, log date, log hour,
and MD5 hash. For example:
Media/2014/07/01/16/096e6c4473f235db081deb51f42a8d98.log.gz
In this example, Media is the name of the container, 2014/07/01 is the date (July 1,
2014), and 16 is the hour that the log file was created. There might be multiple files for a
given hour because the storage system splits log files based on both time and log file size.
All times in the logs are UTC time. All logs contained in the log file are from the day and
hour specified in the file name.
Within the gzip logs, the format of the entries is similar to National Center for Supercomputing Applications (NCSA) combined log format, but without cookies. The pattern follows.
The dashes (-) denote fields that the NCSA combined log format dictates be present but
that Cloud Files does not capture.
client_ip - - [day/month/year:hour:minute:second timezone]
“method request HTTP_version” return_code bytes_sent “referrer”
“user_agent”
The following example shows log entries.
Example 10.8. Example CDN log entries
173.203.44.122 - - [15/07/2014:20:52:25 +0000] "GET
/5142b6e5e57f760d7ff4-c591437fc634f2a98934b7738b8b8571.r93.cf1.rackcdn.
com/image1.png HTTP/1.1" 304 277 "-" "Mozilla/4.0 (compatible;
MSIE 7.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.
50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0;
InfoPath.3; .NET4.0C; .NET4.0E; MS-RTC LM 8; Microsoft Outlook 14.0.
7109; ms-office; MSOffice 14)"
173.203.44.122 - - [15/07/2014:20:52:25 +0000] "GET
com/ email.png HTTP/1.1" 304 278 "-" "Mozilla/4.0 (compatible;
124
May 1, 2015
API v1
173.203.44.122 - - [15/07/2014:20:52:25 +0000] "GET
com/ tiny-email.png HTTP/1.1" 304 277 "-" "Mozilla/4.0 (compatible;
173.203.44.122 - - [15/07/2014:20:59:44 +0000] "GET
com/ default.css?ver=3.8.3 HTTP/1.1" 200 17511 "http://www.rackspace.
com/" "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML,
like Gecko) Chrome/35.0.1916.153 Safari/537.36"
173.203.44.122 - - [15/07/2014:20:59:44 +0000] "GET
com/ jquery.min.js?ver=3.8.3 HTTP/1.1" 200 8022 "http://www.rackspace.
com/" "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML,
like Gecko) Chrome/35.0.1916.153 Safari/537.36"
125
May 1, 2015
API v1
11. Static websites using CDN-enabled
containers
This chapter describes how to use your CDN-enabled containers to create static websites in
Cloud Files.
11.1. Create a static website
You can use your Cloud Files account to create a static website. First, you must CDN-enable a storage container. Any HTML or static web pages in the container become available
through a static website after you set the X-Container-Meta-Web-Index header to
index.html or another index page of your choice. You can also create subdirectories in
your website by creating pseudo directories, as outlined in Chapter 6, “Pseudo hierarchical
folders and directories” [85]. Each pseudo directory becomes a subdirectory in the website.
The page you set for X-Container-Meta-Web-Index becomes the index page for every subdirectory in your website. Each of your pseudo directories must contain a file with
that name. So, if you set X-Container-Meta-Web-Index to index.html, you must
have an index.html page in each pseudo directory. For example, suppose that you have
a subdir pseudo directory. If you do not have an index.html page in subdir, visits to
myhost/subdir/ return a status code 404 (Not Found).
You also have the option of displaying a list of HTML files in your pseudo directory, instead
of a web page. You do this by setting the X-Container-Meta-Web-Listings header to True. If listings are enabled, you can add styles to your file list by setting X-Container-Meta-Web-Listings-CSS to a style sheet. For example, setting X-Container-Meta-Web-Listings-CSS: listing.css makes listings link to the listing.css
style sheet. To view the HTML elements to which you can add styles, use your browser to
view the HTML source on the listing page.
You can modify the Content-Type of directory marker objects by setting the X-Container-Meta-Web-Directory-Type header. If this header is not set, application/directory is used by default. Directory marker objects are 0-byte objects that represent directories to create a simulated hierarchical structure.
The following instructions describe using a CNAME with your DNS Server (or name server).
The CNAME is the domain name of your site (such as www.rackspace.com). Your CNAME
is set up with your individual DNS Server. For more information about using CNAMEs, see
the Cloud DNS Developer Guide at docs.rackspace.com. After your CNAME is established,
set the CNAME to your Cloud Files CDN URI to get your site up and running on the web.
Set up a static website
Following are the step-by-step instructions for setting up a static website.
1. Create a container.
2. Upload your pages to the container.
126
May 1, 2015
API v1
3. Set the index (or primary page) for your website by performing a POST request to the
header X-Container-Meta-Web-Index on your website's container. See Example 11.1, “Set up static web” [127]. (Remember to change the X-Auth-Token to
your authentication token.) You must use your storage URL and the container name to
properly point to the container (storageURL/containerName).
(You get your authentication token when you authenticate your session as shown in Section 3.1: “Authentication”.)
4. CDN-enable your container as shown in Chapter 9: “API operations for CDN services”.
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 that you use instead of the CDN URI. If you need
to find your CDN URI, perform a HEAD request to cdn.clouddrive.com as shown in
the description of the operation to list metadata for a CDN-enabled container in Chapter 9: “API operations for CDN services”.
6. To view your website online, visit your CDN URI or your CNAME domain.
Example 11.1. Set up static web
cURL -X POST -H "X-Container-Meta-Web-Index: index.html" -H "X-Auth-Token:
f064c46a782c444cb4ba4b6434288f7c" "https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_a55df/MyLibrary/"
After your container has an index page set and your domain host has your CNAME recorded, your static website is ready.
Example 11.2. Container setup for static website
container/index.html
container/page2.html
container/subdir/index.html
container/subdir/pageX.html
In the following results, the CNAME is myhost, and the X-Container-Meta-Web-Index is set to index.html. The results on the right of the example are the pages that display in the web browser.
Example 11.3. Static website enabled container results
http://myhost
http://myhost/page2.html
http://myhost/subdir
http://myhost/subdir/
http://myhost/subdir/pageX.html
Displays
Displays
Displays
Displays
Displays
container/index.html
container/page2.html
container/subdir/pageX.html
Note
To disable a static website that you have created, send a request to remove the
metadata header that created the static web site (for example, X-Container-Meta-Web-Index in Example 11.1, “Set up static web” [127]). For more
information, see "Delete container metadata".
127
May 1, 2015
API v1
11.2. Set error pages for a static website
You can create and set custom error pages for visitors to your website. To do this, set the
X-Container-Meta-Web-Error metadata header. 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 that
you set. For example, if you set X-Container-Meta-Web-Error to error.html, 401
errors display the page 401error.html. Similarly, 404 errors display 404error.html.
You must have both of these pages created in your container when you set the X-Container-Meta-Web-Error metadata, or your site will display generic error pages.
Set the X-Container-Meta-Web-Error metadata once for your entire static website.
Example 11.4. Set error pages for static website: HTTP request
1
X-Container-Meta-Web-Error: error.html
Any class 200 status code indicates success.
128
May 1, 2015
API v1
12. Bulk operations
This chapter describes bulk operations that are available with Cloud Files.
12.1. Extracting archive files
An extract archive request expands tar files into a Cloud Files account. The request is a PUT
operation with the ?extract-archive=format query parameter specifying the format
of the archive file.
Valid values for the format variable are tar, tar.gz, and tar.bz2.
Note
This bulk operation involves middleware that conducts many operations on a
single request.
For the PUT request, use the following URI:
/v1/AUTH_Account/$UPLOAD_PATH?extract-archive=tar.gz
UPLOAD_PATH is the location where the files are expanded and can specify any of the following values:
• A container
• A pseudo directory within a container
• An empty string
If the UPLOAD_PATH is an empty string, Cloud Files automatically creates containers in
which to place the files. Files in the base directory of the tar file (that is, files that are not
in a folder of the unzipped tar file) are ignored.
The destination of a file in the archive is built as follows:
/v1/AUTH_Account/$UPLOAD_PATH/$FILE_PATH
FILE_PATH is the file name from the listing in the tar file.
The following example shows a request to extract an archive.
Example 12.1. Example extract archive request
$ tar cf archive.tar directory_to_be_archived
$ curl -i -XPUT -H'x-auth-token: AUTH_TOKEN'
https://storage101.iad3.clouddrive.com/v1/MossoCloudFS_aaa-aaa-aaa-aaa?
extract-archive=tar -T ./archive.tar
You can create up to 1,000 new containers per extraction request. Also note that only regular files are uploaded. Objects such as empty directories and symlinks are not uploaded.
129
May 1, 2015
API v1
The responses from bulk operations are not like other Cloud Files responses because a short
request body sent from the client could result in many operations on the proxy server and
precautions need to be taken to prevent the request from timing out because of a lack of
activity. To this end, the client always receives a 200 OK response, regardless of the actual
success of the call. The body of the response, which can be delivered over a greater amount
of time, must be parsed to determine the actual success of the operation. In addition, the
client might receive whitespace characters prepended to the response body while the proxy
server is completing the request.
The format of the response body defaults to text plain but can be either JSON or XML
depending on the Accept header. Acceptable formats are text/plain, application/json, application/xml, and text/xml. The following example shows the response body, formatted in JSON, from a successful request.
Example 12.2. Successful extract archive response
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
X-Trans-Id: txa7fd1603cfe04bdb920cd-005191226d
Date: Mon, 13 May 2013 17:27:10 GMT
{
"Number Files Created": 10,
"Response Status": "201 Created",
"Errors": [],
"Response Body": ""
}
The following example shows a response with errors.
Example 12.3. Extract archive response with errors
HTTP/1.1 200 OK
X-Trans-Id: tx9f12e16f047049cc91147-005191245f
Date: Mon, 13 May 2013 17:35:27 GMT
{
"Number Files Created": 10,
"Response Status": "400 Bad Request",
"Errors": [
[
"/v1/AUTH_test/test_cont/big_file.wav",
"413 Request Entity Too Large"
]
],
"Response Body": ""
}
Errors are presented as a list of tuples in the form [objectPath, errorResponse].
The objectPath given is the full path where the object was to be put. The errorRe130
May 1, 2015
API v1
sponse is the HTTP status of the response for that individual PUT operation. After 1,000
errors, processing of the request ends, and the completed response is returned.
If all valid files were uploaded successfully, the Response Status in the response body
is 201 Created. If any files failed to be created, the Response Status corresponds to
the subrequest's error. Possible codes are 400, 401, and 502. In both cases, the Response
Body specifies the number of files successfully uploaded and a list of the files that failed.
(The actual HTTP status code is always 200 OK, so the Response Status in the response
body is the one you should monitor.)
Note
If you send a Content-Type header on the PUT request, the specified Content-Type applies to every object in the archive. If you set Content-Type
to a blank string, Cloud Files determines the Content-Type based on the individual file type. For example, if you have Multipurpose Internet Mail Extensions
(MIME) type files, use a blank string for Content-Type to set the MIME type
for files within the archive.
12.2. Bulk delete
You can delete multiple objects or containers from an account by using a single bulk delete
request, which is a DELETE request with the ?bulk-delete set query parameter.
The Content-Type header of the request, if set, must be set to text/plain. You direct the request to the root of the service endpoints (see Section 3.3, “Service access endpoints” [22]). The body of the DELETE request is a newline-separated list of URL-encoded
objects to delete. You can delete 10,000 objects per request.
Note
This bulk operation involves middleware that conducts many operations on a
single request.
The objects specified in the DELETE request body must be URL-encoded and in the following form:
/containerName/objectName
Containers (which must be empty at time of delete) have the following form:
/containerName
Create a text file similar to the following example, objects_to_delete.txt, with the names of
the objects that you want to delete.
Example 12.4. Create text file for bulk delete request
$ cat objects_to_delete.txt
/containerName/objectName1
131
May 1, 2015
API v1
You can use a cURL request similar to the following example for the bulk delete.
Example 12.5. cURL request for the bulk delete
$ curl -i -XDELETE -H'x-auth-token: f064c46a782c444cb4ba4b6434288f7c' https:/
/storage101.dfw1.clouddrive.com/v1/MossoCloudFS_000000\?bulk-delete -T ./
objects_to_delete.txt
An HTTP request for the bulk delete is similar to the following example.
Example 12.6. HTTP request for the bulk delete
DELETE /v1/MossoCloudFS_000000?bulk-delete HTTP/1.1
Host: storage101.dfw1.clouddrive.com
x-auth-token:f064c46a782c444cb4ba4b6434288f7c
Content-Length: 108
The response is similar to the extract archive responses in that every response is 200 OK and
the response body must be parsed for actual results. The following example shows the response body, formatted in JSON, from a successful request.
Example 12.7. Successful bulk delete response
HTTP/1.1 200 OK
X-Trans-Id: tx52fe4601dde24e2b8e7cb-0051912ca8
Date: Thu, 23 Oct 2014 15:16:41 GMT
{
"Number Not Found": 0,
"Response Status": "200 OK",
"Errors": [],
"Number Deleted": 4,
"Response Body": ""
}
The following example shows a response with errors.
Example 12.8. Bulk delete response with errors
HTTP/1.1 200 OK
X-Trans-Id: tx28552a8cd9cb441dad3ad-0051912d2d
Date: Mon, 13 May 2013 18:13:01 GMT
{
"Number Not Found": 0,
132
May 1, 2015
API v1
"Response Status": "400 Bad Request",
"Errors": [
[
"/v1/AUTH_test/non_empty_container",
"409 Conflict"
]
],
"Number Deleted": 0,
"Response Body": ""
}
The list of errors is a list of tuples in the form [objectPath, errorResponse]. The
objectPath is the full path of where the object (or container) was to be deleted. The errorResponse is the HTTP status of the response for that individual DELETE request.
If all items were successfully deleted (or did not exist), the Response Status is 200 OK.
If any items failed to delete, the Response Status code corresponds to the subrequest's
error. Possible codes are 400, 401, and 502. In all cases, the Response Body specifies the
number of items successfully deleted or not found as well as a list of those that failed. The
return body is formatted in the way specified in the request's Accept header. Acceptable
formats are text/plain, application/json, application/xml, and text/xml.
133
May 1, 2015
API v1
13. Public access to your Cloud Files
account
This section describes ways that you can allow others to place objects into or retrieve objects from your Cloud Files account. With the methods described here, users do not need
your password or login information to have access to your account.
13.1. TempURL
You can use the Temporary URL feature (TempURL) to create limited-time Internet addresses that allow limited access to your Cloud Files account. Using TempURL, you can allow
others to retrieve objects from or place objects in your Cloud Files account for a specified
amount of time. After the specified amount of time expires, access to the account with the
TempURL is denied.
Note
If the access time expires while a large file is being retrieved, the download continues until it is finished. Only the link expires.
Access to your Cloud Files account or website with a TempURL is independent of whether
your account is CDN-enabled. Even if you do not CDN-enable a directory, you can still grant
temporary public access through a TempURL. 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 the TempURL Secret, and is set using the
TempURL metadata key described in the next section. The TempURL is the actual URL.
13.1.1. Set account TempURL metadata key
To create a TempURL, you must first set the X-Account-Meta-Temp-Url-Key metadata header on your Cloud Files account to a key that only you know. This key can be any arbitrary sequence.
Note
Changing the X-Account-Meta-Temp-URL-Key invalidates any previously generated TempURLs within 60 seconds (the cache time for the key). To allow transitioning to a new key without effecting service, Cloud Files supports
up to two keys, specified by X-Account-Meta-Temp-URL-Key and X-Account-Meta-Temp-URL-Key-2. Signatures are checked against both keys,
if present. Testing both keys enables key rotation without invalidating all existing TempURLs — you can create TempURLs with a new key while allowing
TempURLs created with the original key to remain valid. Once all the TempURLs
generated with the old key have been exhausted, you can change or remove
the old key.
134
May 1, 2015
API v1
Example 13.1. Set account metadata key for public access: HTTP request
X-Account-Meta-Temp-Url-Key: yourKey
13.1.2. Create the TempURL
After the metadata is set, you must create an HMAC-SHA1 (RFC 2104) signature. When you
generate the TempURL, you determine which method of access you will grant users, GET
or PUT. You also determine the path to the object to which you are granting access. Lastly,
you set the time for your TempURL to expire in UNIX epoch notation.
In the following examples, a TempURL that will be available for 60 seconds is generated for
the my_cat.jpg object. The key in the examples is the value of X-Account-Meta-TempUrl-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=%s;temp_url_expires=%s' % \
(base_url, object_path, sig, expires)
Be certain to use the full URL to the object, just as you would with a normal request.
In this example, the signature might be da39a3ee5e6b4b0d3255bfef95601890afd80709
and the expire time might translate to 1323479485 because the signature and expire time
completely depend on the time when the code runs. On your website, you would provide a
link to the following URL:
https://storage.clouddrive.com/v1/AUTH_account/container/my_cat.jpg?
temp_url_sig=da39a3ee5e6b4b0d3255bfef95601890afd80709&
temp_url_expires=1323479485
If you do not provide users with the exact TempURL, they get a 401 (Unauthorized) status
code. HEAD queries are allowed if GET or PUT operations are allowed.
135
May 1, 2015
API v1
Example 13.3. Create TempURL (in PHP)
<?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, which you can use to override the
Content-Disposition header and indicate to the browser a file name in which to save
the file. In the following example, you see the usual TempURL without the file name override.
Example 13.5. TempURL without file name override
https://cf-cluster.example.com/v1/AUTH_account/container/object?
temp_url_expires=1323479485
136
May 1, 2015
API v1
In the following example, you see &filename=bob.txt appended to the TempURL to indicate to the browser to save the file as bob.txt:
Example 13.6. TempURL with file name override - Example 1
temp_url_expires=1323479485&
filename=bob.txt
With GET TempURLs, a Content-Disposition header is set on the response so that
browsers interpret this as a file attachment to be saved. The file name chosen is based on
the object name, but you can override this with a filename query parameter. The following example specifies a filename of My Test File.pdf:
Example 13.7. TempURL with file name override - Example 2
filename=My+Test+File.pdf
If you do not want the object to be downloaded, you can cause Content-Disposition: inline to be set on the response by adding the inline parameter to the query
string:
Example 13.8. TempURL with inline query parameter
inline
13.2. FormPost
You can use the FormPost feature to give your website audience a way to upload objects
to your Cloud Files account through a web form. FormPost works by translating a browser
form request into an object PUT operation in Cloud Files (see Section 5.3.2, “Create or update object” [68]). After you enable FormPost on your account, you need only to create the
form in your website by using the guidelines in this section.
As with all objects in Cloud Files, the object file size limit is 5 GB. If your users try to upload
an object larger than 5 GB, they will get a file size error.
13.2.1. Set account metadata key
To allow FormPost actions on your Cloud Files account, you must first set the X-Account-Meta-Temp-Url-Key metadata header on your Cloud Files account to a key that
only you know. This key can be any arbitrary sequence.
After you set the key, do not change it while you still want others to access your account. If
you change it, the actions from a FormPost become invalid (within 60 seconds, which is the
cache time for a key).
137
May 1, 2015
API v1
Note
The POST URI should not include the final container. Include just the version
and your account, like /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3abadb66a880123 shown in the example below. If you include the full path to
the container, the key is not set properly.
Example 13.9. Set account metadata key for public access: HTTP request
X-Account-Meta-Temp-Url-Key: yourKey
13.2.2. Create the form
To communicate between your website and your Cloud Files account, create a form using
the following format in your website:
Example 13.10. 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="hidden" name="x_delete_at" value="<unix-timestamp>" />
<input type="hidden" name="x_delete_after" value="<seconds>" />
<input type="file" name="file1" /><br />
<input type="submit" />
</form>
The parameters and attributes in the form are defined as follows:
• (Required) The form action attribute is the Cloud Files URL (CF-url)
to the destination where files will be uploaded. For example, https://
storage.clouddrive.com/v1/yourAccountID/container. The name of each
uploaded object has the <CF-url> appended to the front of it.
Note
Optionally, you can also include a prefix to separate uploads, such as assigning each user a certain prefix: https://storage.clouddrive.com/v1/
yourAccountID/container/object_prefix.
• (Required) The method attribute must be POST and the enctype must be set as multipart/form-data.
• (Optional) The redirect attribute is the URL of the page that is displayed on your website after the form processes. The URL will have status and message query parameters
added to it, indicating the HTTP status code for the upload (2nn indicates success) and
a possible message for more information if there is an error, such as max_file_size
exceeded.
138
May 1, 2015
API v1
Note
Although the redirect attribute is optional for the form, it must be present
in the HMAC body (shown in the following example). Although redirect
must be present, its value can be an empty string to indicate that no redirect is included on the form.
• (Required) The max_file_size attribute specifies the maximum size in bytes of
the largest single file upload. Because the storage system maximum file size is 5 GB,
max_file_size cannot exceed 5 GB.
• (Required) The max_file_count attribute specifies the maximum number of
files that can be uploaded with the form. If you send more files than specified by
max_file_count, Cloud Files uploads the files as normal until you hit the limit (the
max_file_count value). Then, Cloud Files sends an error when it is trying to create the
file over the max_file_count value.
Note
The max_file_count value used to generate the signature must be the
same as that in the web form.
• (Required) The expires attribute is the UNIX timestamp when the form is invalidated.
This gives your website users a limited time to have the form open. Time must be in UNIX
epoch format.
Note
expires in the web form and expires in the HMAC must be the same.
• (Required) The signature attribute is the HMAC-SHA1 signature of the form. Following
is sample code for computing the signature in Python:
Example 13.11. Generate signature for FormPost
import hmac
from hashlib import sha1
from time import time
path = '/v1/account/container/object_prefix'
redirect = 'https://myserver.com/some-page' # set to '' if redirect not
in form
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 sure to use the full path in your Cloud Files account, from the /v1/ onward.
Note that x_delete_at and x_delete_after (see below) are not used in signature
generation because they are optional attributes.
139
May 1, 2015
API v1
The key value is the value of the X-Account-Meta-Temp-Url-Key header set for the
account.
Note
If you receive the Invalid Signature error, use the HEAD operation described in Section 5.1.3, “Get account metadata” [40] to confirm that your
key matches the value in the response from the HEAD command.
• (Optional)If you want the uploaded files to be temporary, you can set the x-delete-at
or x-delete-after attributes by adding one of these as a form input.
• (Required) The type="file" attribute defines the form file field. You must have at
least one entry to allow your users to select and upload a file, but you can add more
fields for multiple files. However, the number of entries must not exceed the value of
max_file_count. Each type="file" attribute must have a different name.
Note
The type="file" attribute or attributes must be at the end of the form
code for Cloud Files to process the uploads correctly.
13.3. CORS
Cross-Origin Resource Sharing (CORS) is a mechanism that allows code running in a browser
to make requests to a domain other than the one from which it originated by using HTTP
headers, such as those assigned by Cloud Files API requests.
Cloud Files supports CORS requests to containers and objects.
For more information about CORS and the access control headers, see www.w3.org/TR/access-control/.
13.3.1. CORS headers for containers
Container-level headers for CORS are used for the following Cloud Files features:
• FormPost (Section 13.2: “FormPost”), to enable your users to post to your site
• TempURL (Section 13.1: “TempURL ”), to limit how long users can use a given URL
Note
Container-level headers for CORS are not inherited for use with a CDN. For information about using object-level headers, which enable CORS to work over a
CDN, see Section 13.3.2, “CORS headers for objects” [143].
CORS container headers enable your users to upload files from one website, or origin, to
your Cloud Files account. When you set the CORS headers on your container, you provide
Cloud Files with the following information:
140
May 1, 2015
API v1
• 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
CORS metadata is held on the container only. The values given apply to the container itself
and all objects within it.
The following table lists the container-level headers:
Table 13.1. CORS container-level headers
X-Container-Meta-Access-Control-Allow-Origin
Specifies the origins that are allowed to make cross-origin requests, separated by a space when there are multiple values.
X-Container-Meta-Access-Control-Max-Age
Specifies the maximum age for the origin to hold the preflight results, in seconds (for example, 5, 10, or 1000).
X-Container-Meta-Access-Control-Allow-Headers
Specifies the headers that are allowed in the actual request,
separated by a space when there are multiple values.
X-Container-Meta-Access-Control-Expose-Headers
Indicates the headers exposed to the browser in the actual
request response, separated by a space when there are multiple values.
To view the values for these headers, use the HEAD operation to show container metadata.
To delete the metadata, use the DELETE operation to delete container metadata. Both of
these operations are described in Section 5.2, “Container services” [43].
Before a browser issues an actual request, it might issue a preflight request. The preflight
request is an HTTP OPTIONS call to verify that the origin is allowed to make the request.
Following is the sequence of actions:
1. The browser makes an OPTIONS request to Cloud Files.
2. Cloud Files returns either a 200 or 401 status code 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 exposes only those headers listed in the X-Container-Meta-Access-Control-Expose-Headers header. By default, Cloud Files returns the following values for this header:
• The simple response headers as listed at www.w3.org/TR/cors/#simple-response-header/
• The ETag, X-Timestamp, and X-Trans-Id headers
• 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.13, “Test CORS page” [142].
141
May 1, 2015
API v1
2. Host the page on a web server and note the protocol and hostname (origin) you will be
using to request the page, for example http://localhost.
3. Locate a container that you want to query. (The Cloud Files cluster hosting this container
must have CORS support.)
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.12. Example of a CORS POST cURL request
curl -X POST -H 'X-Auth-Token: yourAuthToken' \
-H 'X-Container-Meta-Access-Control-Allow-Origin: http://localhost' \
https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_0672d7fa-9f85-4a81a3ab-adb66a880123/MyContainer
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 field with the URL of either a container or object.
3. Select the request method.
4. Hit Submit.
If the request succeeds, the response header and body are displayed. If the request did not
succeed, the response status is 0.
Example 13.13. 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;">
142
May 1, 2015
API v1
<pre id="response_headers"></pre>
<p>
<hr>
<pre id="response_body"></pre>
<script type="text/javascript">
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>
13.3.2. CORS headers for objects
You can set object-level headers for CORS. Currently, using object-level headers enables
CORS to work over a CDN (Section 2.7: “CDN-enabled containers”).
The following table lists the object-level headers:
Table 13.2. CORS object-level headers
Access-Control-Allow-Ori- Specifies the origins that are allowed to make cross-origin requests, separated by a
gin
space when there are multiple values.
Access-Control-Max-Age
Specifies the maximum age for the origin to hold the preflight results, in seconds
(for example, 5, 10, or 1000).
Access-Control-Expose-Headers
Specifies the headers exposed to the browser in the actual request response, separated by a space when there are multiple values.
Access-Control-Allow-Cre- Indicates whether or not the response to the request can be exposed when the
dentials
credentials flag is true. When used as part of a response to a preflight request,
this indicates whether or not the actual request can be made using credentials. 143
May 1, 2015
API v1
Note that simple GET requests are not preflighted, and so if a request is made for
a resource with credentials, if this header is not returned with the resource, the response is ignored by the browser and not returned to web content.
Access-Control-Allow-Methods
Specifies the method or methods allowed when accessing the resource. This is
used in response to a preflight request. Access-Control-Request-Headers
Used when issuing a preflight request to let the server know what HTTP headers
will be used when the actual request is made.
Access-Control-Request-Method
Used when issuing a preflight request to let the server know what HTTP method
will be used when the actual request is made.
Origin
Indicates the origin of the cross-site access request or preflight request.
The following example assigns the file origin to the Origin header to indicate where the
file came from. Doing so allows you to provide security that requests to your Cloud Files
repository are indeed from the correct origination.
Example 13.14. Assign CORS header request for an object
POST /apiVersion/yourAccountID/containerName/objectName HTTP/1.1
Origin: http://storage.clouddrive.com
144
May 1, 2015
API v1
Glossary
Account
The portion of the Cloud Files system designated for your use. The Cloud Files system is designed
to be used by many different customers, and your user account is your portion of it. Your user account is your slice of the Cloud Files system. You must identify yourself with a valid user name and
your API access key. After you are authenticated, your have full read/write access to the objects
(files) stored under your account.
Application program interface (API)
A set of routines, protocols, and tools for building software applications.
Authentication
The process if identifying yourself to the Rackspace Cloud Identity service to receive Cloud Files
connection parameters and an authentication token. While the authentication token is valid
(which in most cases is 24 hours), you must pass it to Cloud Files to perform all Cloud Files operations.
CDN-enabled containers
Containers that serve content through the Akamai content delivery network (CDN). When a container is CDN-enabled, any files in the container are publicly accessible and do not require an authentication token for read access. However, uploading content into a CDN-enabled container is a
secure operation and requires a valid authentication token. Each published container has a unique
URL that can be combined with its object name and openly distributed in web pages, emails, or
other applications. For example, a CDN-enabled container named photos can be referenced as
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.rackcdn.com.
If that container houses an image called mydog.jpg, that image can be served by the Akamai CDN with the full URL of
http://80745c48926cd286a5a0-48261ebe0e4c795a565ece6b9cca2fe8.r10.cf1.rackcdn.com/
mydog.jpg..
Container
A storage compartment that provides a way for you to organize data. A container is similar to a
folder in Windows or a directory in UNIX. The primary difference between a container and these
other file system concepts is that containers cannot be nested.
Content delivery network (CDN)
A system of distributed servers (network) that delivers web pages and other web content to a user based on the geographic locations of the user, the origin of the web page, and a content delivery server.
Language-specific API
APIs that provide a layer of abstraction on top of the base REST API, enabling programmers to
work with a container and object model instead of working directly with HTTP requests and responses. Language-specific APIs in several popular languages are available for Cloud Files.
Metadata
Optional information that you can assign to Cloud Files accounts, containers, and objects through
the use of a metadata header.
Middleware
Software that connects two otherwise separate applications. For example, there are a number of
middleware products that link a database system to a web server.
145
May 1, 2015
API v1
Operations
The actions you perform against your account in Cloud Files, such as creating or deleting containers. Operations are performed via the REST web service API or a language-specific API.
Private container
A container that is only accessible by the account holder.
Pseudo directories
A hierarchical structure within a single Cloud Files container created adding forward slash characters (/) in the object name.
Public container
A CDN-enabled container that is publicly accessible.
REST
REST, short for Representational State Transfer, is an architectural style for large-scale software
design.
Segmentation
The process of segmenting a large file into a number of smaller files for uploading to Cloud Files.
Cloud Files limits 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 use 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. Segmentation also offers much greater upload speed with the possibility of parallel uploads of the segments.
TTL
Time-to-live value.
146

Rackspace Cloud Filesâ¢ Developer Guide

Transcription

Similar documents

Please this as a Flyer TODAY!

Life Science Sample Questions

Document 6520796

How to transport exotic species properly Brussels 5 October 2012

CTAA READY RECKONER CONTAINER PACKS & UNPACKS

Chapter 10: Motivating Employees and Building Self Managed

Our 45` HC pallet-wide container carries five more feet of

L O C K M A S T E R... Standard Form 700 (Sf 700) Security Container Information

instructions

Our 45` HC pallet-wide container carries five more feet of

Rackspace Cloud Filesâ¢ Developer Guide

Transcription

Similar documents

Rackspace Cloud Filesâ¢ Developer Guide