Professional Documents
Culture Documents
Rackspace Cloud Files - Developer Guide (20150825)
Rackspace Cloud Files - Developer Guide (20150825)
Rackspace Cloud Files - Developer Guide (20150825)
com/api
API v1
ii
API v1
Table of Contents
1. Overview ..................................................................................................................... 1
1.1. Intended audience ........................................................................................... 1
1.2. Document change history ................................................................................. 2
1.3. Additional resources ......................................................................................... 6
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
API v1
iv
API v1
List of Figures
4.1. Cloud Files system interfaces ................................................................................... 29
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 .............................................................................. 140
13.2. CORS object-level headers ................................................................................... 142
vi
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
API v1
viii
API v1
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
127
128
129
129
130
131
131
131
131
134
134
135
135
135
136
136
136
137
137
138
141
141
143
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
support@rackspacecloud.com.
1.1.Intended audience
This guide is intended to assist software developers who want to develop applications using the Rackspace Cloud Files API. It fully documents the REST application programming interface (API) that allows developers to interact with the storage and CDN components of
the Cloud Files system. To use the information provided here, you 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.
API v1
Summary of Changes
In the Copy object operation description, corrected the X-Copy_From request header description to be X-Copy-From.
In the Copy object operation description, added the X-Copy-From-Account header description for requests.
Updated Set error pages for a static website to clarify that you can set the X-Container-Meta-Web-Error header only to error.html.
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.
Corrected the URI in the table in Section9.3, CDN object services [116] 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 Section3.1, Authentication [11].
Added the account to account copy capability described in Section8.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.
Updated Section3.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.
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 Section3.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".
Updated Section13.1.1, Set account TempURL metadata key [133] 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 Section13.3, CORS [139]. This section now includes the following subsections
to describe the available access control headers:
Section13.3.1, CORS headers for containers [139]
Section13.3.2, CORS headers for objects [142]
Added a note to Section11.1, Create a static website [125] about how to disable a static website that you have created.
Revision Date
API v1
Summary of Changes
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.
Corrected the link to service access endpoint information in "List CDN-enabled containers".
Corrected an error in the Python example to create a TempURL in Section13.1.2, Create the
TempURL [134]. (Removed AMP from the last print in the example.)
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 Section10.5, CDN log delivery [122].
Updated the TTL maximum value to 1 year (31536000 seconds) instead of 50 years
(1577836800 seconds) throughout Chapter9, 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
April 1, 2014
Added header descriptions to the operations in Chapter5, API operations for storage services [30].
Updated the "Bulk importing of data"section to show the availability of using this feature in
Sydney.
Updated the table in Section3.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 Chapter5, API operations for storage services [30] and Chapter9, API operations for CDN services [105] by using Web Application Description Language (WADL)
files for the resource and method descriptions.
Updated the instructions for locating the API key in the Cloud Control Panel in Section3.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 Section3.3,
Service access endpoints [22].
Updated account information in Section3.3, Service access endpoints [22] to show
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee rather than 1234.
Added Section3.4, Cloud Files service contract version [25].
Added Section3.5, Absolute limits [25].
Added Section3.6, Request and response types [26].
Revision Date
API v1
Summary of Changes
Added the section for the operation to create or update account metadata in Chapter5,
API operations for storage services [30].
Added the section for the operation to delete account metadata in Chapter5, API operations for storage services [30].
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.
Added Section8.2, Creating large objects [91] with more information about dynamic
large objects and static large objects.
Updated Section12.1, Extracting archive files [128] to include a note about using a
blank Content-Type header to have Cloud Files determine the file type for the archive.
Added service catalog information for cloudfilesCDN endpoints (Section3.3, Service access endpoints [22]).
Made miscellaneous updates throughout this book to improve wording and consistency.
November 1, 2013
Added Section3.3, Service access endpoints [22], which includes all endpoints for
Cloud Files including the newest one in Hong Kong.
Updated Section3.1, Authentication [11] to show information for Rackspace Identity
v2.0.
Updated Section13.2.2, Create the form [137] to indicate that the value of the redirect parameter can be empty to indicate that no redirect is included on the form.
Clarified information about the redirect and expires parameters in Section13.2.2, Create the form [137].
Added a link in Chapter1, 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 Section7.2, Container quotas [88].
Created a new section Section5.3, Object services [62]. This section includes new and
previously existing information specifically related to storage objects.
Added Section8.2.2, Creating a static large object [95].
Added Chapter12, Bulk operations [128].
Added Section13.1.3, Override TempURL file names [135].
February 1, 2013
Changed the location of SDKs. Added a note about object metadata behavior.
Revision Date
API v1
Summary of Changes
December 5, 2012
October 1, 2012
June 1, 2012
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.
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.
Revised information about how to perform a CDN purge, indicating that you must contact
support to request a container purge operation.
Added more detail about reasons to perform a CDN purge, clarifying that it is not required
for deleting objects.
Added information about streaming containers to support the new streaming feature, including changing examples to match the streaming headers and URLs returned.
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.
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.
Added information about the edge purge capability for CDN-enabled containers and objects.
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 4, 2011
May 5, 2008
Initial release.
API v1
1.3.Additional resources
You can download the most current version of this document from the Rackspace API documentation website at docs.rackspace.com.
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.
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
Section3.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 Section3.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
Section3.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
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 Section3.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 Section7.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 Chapter5, API operations for storage services [30]. The operations are then described in
the following REST API sections:
Section5.1, Account services [31]
8
API v1
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 Section9.3, CDN object services [116].
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
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 Chapter9, 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 sdk-support@rackspace.com. 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
API v1
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/
v2.0/tokens
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
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.
12
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 componentsyour 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.
13
API v1
14
API v1
internalURL="https://snet-storage101.hkg1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"/>
</service>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
<endpoint region="SYD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://cdn4.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
<endpoint region="IAD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://cdn5.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
<endpoint region="HKG"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://cdn6.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeeeeeee"/>
</service>
<service type="rax:dns" name="cloudDNS">
<endpoint tenantId="1100111"
publicURL="https://dns.api.rackspacecloud.com/v1.0/1100111"/>
</service>
</serviceCatalog>
</access>
15
API v1
}
]
},
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://dfw.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudDatabases",
"type": "rax:database"
},
{
"endpoints": [
{
"publicURL": "https://dfw.loadbalancers.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.loadbalancers.api.
rackspacecloud.com/v1.0/1100111",
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudLoadBalancers",
"type": "rax:load-balancer"
},
{
"endpoints": [
{
"tenantId": "1100111",
"region": "DFW",
"publicURL": "https://dfw.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://dfw.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://dfw.servers.api.
rackspacecloud.com/"
},
{
"tenantId": "1100111",
"region": "ORD",
"publicURL": "https://ord.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
16
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"
},
{
"publicURL": "https://cdn4.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "SYD",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"publicURL": "https://cdn5.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "IAD",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"publicURL": "https://cdn6.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "HKG",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"publicURL": "https://cdn2.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "ORD",
17
API v1
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
}
],
"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",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"internalURL": "https://snet-storage101.syd2.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"publicURL": "https://storage101.syd2.clouddrive.com/
v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880321",
"region": "SYD",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"internalURL": "https://snet-storage101.iad3.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"publicURL": "https://storage101.iad3.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "IAD",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"internalURL": "https://snet-storage101.ord1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"publicURL": "https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "ORD",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
},
{
"internalURL": "https://snet-storage101.hkg1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"publicURL": "https://storage101.hkg1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"region": "HKG",
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeeeeeee"
}
],
"name": "cloudFiles",
"type": "object-store"
},
{
"endpoints": [
18
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
API v1
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
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 Section3.3, Service access endpoints [22].
Note
The account owner (identity:user-admin) role cannot hold any additional roles
because it already has full access to all capabilities.
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
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.
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.
View of permission
in the Control Panel
Can the user perform product admin functions in the Control Panel?
API v1
Endpoint
https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://storage101.dfw1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.dfw1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://storage101.hkg1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.hkg1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
London (LON)
https://storage101.lon3.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.lon3.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://storage101.iad3.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.iad3.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
Sydney (SYD)
https://storage101.syd2.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://snet-storage101.syd2.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
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 Table3.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
API v1
and response in Section3.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 Chapter9, API
operations for CDN services [105].
Endpoint
Chicago (ORD)
https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://cdn6.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
London (LON)
https://cdn3.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
https://cdn5.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
Sydney (SYD)
https://cdn4.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/
As with the storage component service, replace the sample MossoCloudFS 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
API v1
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.
Table3.5.Absolute limits
Name
Description
Limit
500,000 containers
Container listing
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
256 bytes
1024 bytes
25
API v1
Name
Description
Limit
10 GB
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
Description
OK
200
Created
201
Accepted
202
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
Unauthorized
401
Authentication failed, or the user does not have permissions for a requested operation.
Forbidden
403
Not Found
404
A requested resource was not found but might be available again in the future..
405
Request Timeout
408
Conflict
409
Length Required
411
Precondition Failed
412
26
API v1
Description
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
429
500
Service Unavailable
503
27
API v1
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 Section3.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 Section3.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 Section3.1.2, Retrieving the authentication token [11]) manages the CDN
feature of Cloud Files.
28
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.
29
API v1
URI
Description
Account services
GET
/v1/{account}{?limit,marker,
end_marker,format,prefix,delimiter}
POST
/v1/{account}
HEAD
/v1/{account}
POST
/v1/{account}
GET
/v1/{account}/{container}{?limit,
marker,end_marker,prefix,format,
delimiter,path}
PUT
/v1/{account}/{container}
Creates a container.
DELETE
/v1/{account}/{container}
POST
/v1/{account}/{container}
Creates or updates the container metadata by associating custom metadata headers with the container-level
URI. These headers must have the format X-Container-Meta-name.
HEAD
/v1/{account}/{container}
Shows container metadata, including the number of objects in the container and the total bytes for all objects
stored in the container.
POST
/v1/{account}/{container}
GET
Object services
30
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
COPY
HEAD
POST
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 Section3.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
/v1/{account}{?limit,marker,
end_marker,format,prefix,delimiter}
POST
/v1/{account}
HEAD
/v1/{account}
POST
/v1/{account}
31
API v1
URI
Description
/v1/{account}{?limit,marker,
end_marker,format,prefix,delimiter}
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
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
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
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
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
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
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
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
apples
bananas
kiwis
This table shows the possible response codes for this operation:
33
Name
API v1
Description
200
OK
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
404
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
(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.
34
API v1
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
(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
(Required)
bytes
Int
(Required)
35
36
API v1
[
{
"count": 0,
"bytes": 0,
"name": "janeausten"
},
{
"count": 1,
"bytes": 14,
"name": "marktwain"
}
]
37
API v1
API v1
URI
Description
Creates or updates account metadata.
/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.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
400
Bad Request
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
Authentication token.
(Required)
X-Account-Meta-Temp-URLKey
String
X-Account-Meta-Temp-URLKey-2
String
X-Account-Meta-name
String
(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
Your unique account identifier.
38
API v1
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
39
API v1
URI
Description
Gets account metadata.
/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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
401
Unauthorized
5.1.3.1.Request
This table shows the header parameters for the get account metadata request:
Name
X-Auth-Token
Type
String
Description
Authentication token.
(Required)
X-Auth-Token
String
Authentication token.
(Required)
This table shows the URI parameters for the get account metadata request:
Name
{account}
Type
String
Description
Your unique account identifier.
5.1.3.2.Response
This table shows the header parameters for the get account metadata response:
40
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.
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
Accept-Ranges
String
(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
(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.
41
API v1
URI
Description
Deletes account metadata.
/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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
400
Bad Request
5.1.4.1.Request
This table shows the header parameters for the delete account metadata request:
Name
X-Auth-Token
Type
String
Description
Authentication token.
(Required)
X-Account-Meta-Temp-URLKey
String
X-Account-Meta-Temp-URLKey-2
String
X-Remove-Account-Metaname
String
(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)
This table shows the URI parameters for the delete account metadata request:
Name
{account}
Type
String
Description
Your unique account identifier.
42
API v1
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
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
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
5.2.Container services
You can perform the operations in the following table on containers in 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
container for example, MyContainer
For your own requests, you must use your own account information, authentication token,
and container names. For more information, see Section3.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
/v1/{account}/{container}{?limit,
marker,end_marker,prefix,format,
delimiter,path}
PUT
/v1/{account}/{container}
Creates a container.
DELETE
/v1/{account}/{container}
POST
/v1/{account}/{container}
Creates or updates the container metadata by associating custom metadata headers with the container-level
43
URI
API v1
Description
URI. These headers must have the format X-Container-Meta-name.
HEAD
/v1/{account}/{container}
Shows container metadata, including the number of objects in the container and the total bytes for all objects
stored in the container.
POST
/v1/{account}/{container}
44
API v1
URI
Description
/v1/{account}/{container}{?limit,
marker,end_marker,prefix,format,
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
API v1
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
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
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
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
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.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
200
OK
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(Required)
Accept
String
Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.
46
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
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.
5.2.1.2.Response
This table shows the header parameters for the show container details and list objects response:
47
Name
Type
Content-Length
String
X-Container-Object-Count
Int
API v1
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.
The number of objects.
(Required)
Accept-Ranges
String
(Required)
X-Container-Bytes-Used
Int
(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
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.
A unique transaction identifier for this request.
(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
(Required)
last-modified
String
48
<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>
49
API v1
API v1
5.2.2.Create container
Method
PUT
URI
Description
Creates a container.
/v1/{account}/{container}
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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
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
5.2.2.1.Request
This table shows the header parameters for the create container request:
Name
X-Auth-Token
Type
String
Description
Authentication token.
(Required)
X-Container-Meta-name
String
(Optional)
50
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
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
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.
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
51
52
API v1
API v1
5.2.3.Delete container
Method
DELETE
URI
Description
Deletes an empty container.
/v1/{account}/{container}
A DELETE operation against a storage container permanently removes it. The container
must be empty before it can be deleted.
Before using DELETE, you can use a GET operation against the container to list any objects
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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(Required)
This table shows the URI parameters for the delete container request:
Name
Type
Description
{account}
String
{container}
String
5.2.3.2.Response
This table shows the header parameters for the delete container response:
53
Type
Content-Length
String
Content-Type
String
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.
(Required)
X-Trans-Id
API v1
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
54
API v1
URI
Description
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.
/v1/{account}/{container}
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.
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
Host: storage.clouddrive.com
X-Auth-Token: yourAuthToken
X-Container-Meta-Price: 45
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-Price: 45
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.
This operation does not require a request body and does not return a response body.
55
API v1
Note
For information about adding metadata for the following purposes, see Get object content and metadata:
Container quotas
Access log delivery
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(Required)
X-Container-Meta-name
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.
(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
API v1
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
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.
(Required)
X-Trans-Id
Description
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
57
API v1
URI
Description
Shows container metadata, including the number of objects in the container and the total bytes for all objects
stored in the container.
/v1/{account}/{container}
Use a HEAD operation against the container to return the following metadata:
How many objects are in the container (X-Container-Object-Count)
The total bytes for all objects stored in the container (X-Container-Bytes-Used)
Any custom metadata that is set on the container (X-Container-Meta-name)
To set and edit your custom metadata, see 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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(Required)
This table shows the URI parameters for the show container metadata request:
Name
Type
Description
{account}
String
{container}
String
58
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)
X-Container-Meta-name
String
Any metadata set on the container. The name at the end of the header is the name of your metadata. 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
(Required)
X-Trans-Id
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
Accept-Ranges
String
(Required)
X-Versions-Location
String
59
X-Container-Meta-Author: SamuelClemens
X-Container-Bytes-Used: 14
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
Date: Thu, 16 Jan 2014 18:37:22 GMT
60
API v1
API v1
URI
Description
Deletes container metadata.
/v1/{account}/{container}
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.
This operation does not require a request body and does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(Required)
X-Remove-Container-Metaname
String
X-Container-Read
String
X-Container-Write
String
(Required)
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
Your unique account identifier.
61
Name
{container}
Type
String
API v1
Description
The unique identifier of the container.
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
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.
(Required)
X-Trans-Id
Description
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
5.3.Object services
You can perform the operations in the following table on objects in your Cloud Files containers.
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
container for example, MyContainer
object for example, MyObject
For your own requests, you must use your own account information, authentication token,
container names, and object names. For more information, see Section3.1.2, Retrieving
the authentication token [11]. Your authentication token and your account information
are in the service catalog that is produced.
62
URI
API v1
Description
GET
PUT
/v1/{account}/{container}/{object} Creates or updates the content and metadata for a speci{?signature,expires,multipart-man- fied object.
ifest}
DELETE
COPY
HEAD
POST
63
API v1
URI
Description
If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
Range: bytes=-5
Range: bytes=10-15
Range: bytes=10-15,-5
Range: bytes=4-6
Bytes 4 through 6.
Range: bytes=2-2
Range: bytes=6-
Range: bytes=1-3,2-5
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
API v1
Note
In the following examples that use ranges, the object contains the 10 bytes of
data 0123456789.
This table shows the possible response codes for this operation:
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
Authentication token.
(Required)
This table shows the URI parameters for the get object content and metadata request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
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
65
API v1
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Range: bytes=4-6
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
(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, 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
Name
Type
API v1
Description
(Required)
Date
Datetime
(Required)
67
API v1
URI
Description
/v1/{account}/{container}/{object} Creates or updates the content and metadata for a speci{?signature,expires,multipart-man- fied object.
ifest}
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
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.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
201
Created
202
Accepted
401
Unauthorized
411
Length Required
422
Unprocessable Entity
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
Authentication token.
(Required)
ETag
String
(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)
X-Detect-Content-Type
Boolean
X-Object-Manifest
String
If you set this header to True, the Content-Type that is sent in the
request (if any) is ignored, and Content-Type is guessed by using
(Optional) the Python mimetypes library based on the object path.
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
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
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
5.3.2.2.Response
This table shows the header parameters for the create or update object response:
Name
Content-Length
Type
String
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.
70
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)
71
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.
This operation does not require a request body and does not return a response body.
For information about bulk deletions, see Bulk delete.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Authentication token.
(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
Type
API v1
Description
String
5.3.3.2.Response
This table shows the header parameters for the delete object response:
Name
Type
Content-Length
String
Content-Type
String
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.
(Required)
X-Trans-Id
Description
Uuid
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.
A unique transaction identifier for this request.
(Required)
Date
Datetime
(Required)
73
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.
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.
74
API v1
Host: storageURL
X-Auth-Token: yourAuthToken
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.)
This table shows the possible response codes for this operation:
75
Name
API v1
Description
201
Created
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
Authentication token.
(Required)
X-Copy-From
String
(Optional)
X-Copy-From-Account
String
Used with PUT, the container and object name of the source object in
the form of /container/object.
Specifies the account you are copying from.
(Optional)
Content-Length
Int
(Required)
Destination
String
(Optional)
Destination-Account
String
(Optional)
Content-Type
String
X-Detect-Content-Type
String
Content-Encoding
String
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).
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.
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.
If set, the value of the Content-Encoding metadata.
(Optional)
Content-Disposition
String
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.
X-Object-Meta-name
String
This table shows the URI parameters for the copy object request:
Name
Type
Description
{account}
String
{container}
String
{object}
String
76
API v1
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Destination: /MyDestinationContainer/MyDestinationObject
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
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.
The MD5 checksum of the uploaded object content. The value is not
quoted.
The MIME type of the object.
(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
The custom object metadata item, where name is the name of the
metadata item. One X-Object-Meta-name response header ap(Required) pears for each metadata item (for each name).
77
78
API v1
API v1
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.
This table shows the possible response codes for this operation:
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.5.1.Request
This table shows the header parameters for the show object metadata request:
Name
X-Auth-Token
Type
String
Description
Authentication token.
(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
Used with temporary URLs to sign the request. For more information
about temporary URLs, see TempURL .
79
Type
String
expires
(Optional)
API v1
Description
Used with temporary URLs to specify the expiry time of the signature.
For more information about temporary URLs, see TempURL .
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
(Required)
Etag
String
(Required)
Content-Type
String
The MD5 checksum of the uploaded object content. The value is not
quoted.
The MIME type of the object.
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
Content-Encoding
String
(Optional)
Content-Disposition
String
X-Delete-At
String
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.
80
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
The custom object metadata item, where name is the name of the
metadata item. One X-Object-Meta-name response header ap(Required) pears for each metadata item (for each name).
81
API v1
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.
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
Host: storage.clouddrive.com
X-Auth-Token: yourAuthToken
X-Object-Meta-Price: 45
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-Price: 45
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
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.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
202
Accepted
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
Authentication token.
(Required)
X-Object-Meta-name
String
(Optional)
X-Delete-At
Int
(Optional)
X-Delete-After
Int
(Optional)
Content-Type
String
X-Detect-Content-Type
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.
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.
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.
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 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
83
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
The length of the object content in the response body, in bytes.
(Required)
Content-Type
String
(Required)
X-Trans-Id
Uuid
(Required)
Date
Datetime
(Required)
84
API v1
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
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
API v1
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.
87
API v1
Repeat the operation to show container metadata and confirm the metadata change.
For more information about ACLS and using them with RBAC (Section3.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
API v1
be useful for limiting containers for non-admin users, FormPost uploads, or just as a sanity
check. (For information about FormPost, see Section13.2, FormPost [136]).
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 Section8.1,
Chunked transfer encoding [91].
You set quotas by adding metadata to the container. The available metadata values are described in the following table.
Description
X-Container-Meta-Quota-Bytes
X-Container-Meta-Quota-Count
API v1
90
API v1
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
API v1
End-to-end integrity
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.
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).
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.
93
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.
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
API v1
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.
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.
API v1
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
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.
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 Section5.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
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.
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.
API v1
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.
99
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/.
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
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
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.
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
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/
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.
Response:
204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx1abc1d6005134be99b1db-0054da619adev1
Date: Tue, 10 Feb 2015 19:52:58 GMT
Response:
103
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
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txd819a3f557de449cb0879-0054da6334dev1
Date: Tue, 10 Feb 2015 19:59:48 GMT
Response:
204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx0f6c102033564bb0800e3-0054da677fdev1
Date: Tue, 10 Feb 2015 20:18:07 GMT
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
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe3373a175f944020a63d9-0054da74c9dev1
Date: Tue, 10 Feb 2015 21:14:49 GMT
104
API v1
URI
Description
CDN account services
GET
/v1/{account}{?limit,marker,
end_marker,format}
/v1/{account}/{container}
HEAD
/v1/{account}/{container}
POST
/v1/{account}/{container}
DELETE
API v1
For your own requests, you must use your own account information and authentication token. For more information, see Section3.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
/v1/{account}{?limit,marker,
end_marker,format}
106
API v1
URI
Description
/v1/{account}{?limit,marker,
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.)
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.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
200
OK
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
Your unique account identifier.
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
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)
107
API v1
9.1.1.2.Response
Example9.3.List CDN-enabled containers: HTTP response
HTTP/1.1 200 OK
Date: Thu, 08 Sep 2011 14:35:45 GMT
Transfer-Encoding: chunked
Content-Type: text/plain
images
movies
API v1
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
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.
URI
Description
PUT
/v1/{account}/{container}
HEAD
/v1/{account}/{container}
POST
/v1/{account}/{container}
109
API v1
URI
Description
Enables or disables a container for use with the CDN.
/v1/{account}/{container}
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.
This operation does not require a request body and does not return a response body.
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 contain110
API v1
er 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
This table shows the possible response codes for this operation:
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.
202
Accepted
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
(Optional)
This table shows the URI parameters for the cdn-enable and cdn-disable a container request:
Name
Type
Description
{account}
String
{container}
String
111
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
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.
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 transaction date and time.
(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.
A unique transaction identifier for this request.
(Required)
112
API v1
URI
Description
Gets a CDN-enabled container's metadata.
/v1/{account}/{container}
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.)
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.
This table shows the possible response codes for this operation:
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.
204
No Content
The request succeeded. The server fulfilled the request but does not
need to return a body.
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
9.2.2.2.Response
This table shows the header parameters for the list metadata for cdn-enabled container response:
113
Name
Type
X-Cdn-Uri
String
X-Ttl
Int
X-Cdn-Enabled
Boolean
Boolean
(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-Ios-Uri
Description
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.
(Required)
X-Log-Retention
API v1
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.
114
API v1
URI
Description
Updates the CDN-enabled container's metadata.
/v1/{account}/{container}
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.
This table shows the URI parameters for the update cdn-enabled container metadata request:
Name
Type
Description
{account}
String
{container}
String
115
API v1
X-Ttl: 86400
X-Cdn-Enabled: True
X-Log-Retention: True
9.2.3.2.Response
Example9.11.Update CDN-enabled container metadata: HTTP response
HTTP/1.1 204 No Content
X-Cdn-Ssl-Uri: https://83c49b9a2f7ad18250b3-346eb45fd42c58ca13011d659bfc1ac1.
ssl.cf0.rackcdn.com
X-Ttl: 259200
X-Cdn-Uri: http://081e40d3ee1cec5f77bf-346eb45fd42c58ca13011d659bfc1ac1.r49.
cf0.rackcdn.com
X-Cdn-Enabled: True
X-Log-Retention: False
X-Cdn-Streaming-Uri: http://
084cc2790632ccee0a12-346eb45fd42c58ca13011d659bfc1ac1.r49.stream.cf0.rackcdn.
com
X-Trans-Id: tx82a6752e00424edb9c46fa2573132e2c
Content-Length: 0
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 Table3.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
116
API v1
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
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb63f31d26bf84c058542b-0055101cd0dfw1
Date: Mon, 23 Mar 2015 14:01:52 GMT
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.
This operation does not return a response body.
This table shows the possible response codes for this operation:
Response
Code
Name
Description
204
No Content
The server fulfilled the request but does not need to return a body.
403
Forbidden
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
9.3.1.2.Response
Example9.13.Delete CDN-enabled object: HTTP response
HTTP/1.1 204 No Content
Content-Type: text/html; charset=UTF-8
Content-Length: 0
118
X-Trans-Id: txd57d75dcd51e4a79a886d-0055101ecford1
Date: Mon, 23 Mar 2015 14:10:25 GMT
119
API v1
API v1
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 Chapter9, API operations for CDN services [105].
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 Section10.4, iOS streaming [121].
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 Chapter9: 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.
121
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.
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.
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.
With these pieces of code in place, the proper content streams are set for iOS devices.
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.
123
API v1
124
API v1
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 Example11.1, Set up static web [126]. (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 Section3.1: Authentication.)
4. CDN-enable your container as shown in Chapter9: 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 Chapter9: API operations for CDN services.
6. To view your website online, visit your CDN URI or your CNAME domain.
After your container has an index page set and your domain host has your CNAME recorded, your static website is ready.
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.
Displays
Displays
Displays
Displays
Displays
container/index.html
container/page2.html
container/subdir/index.html
container/subdir/index.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 Example11.1, Set up static web [126]). For more
information, see "Delete container metadata".
126
API v1
127
API v1
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.
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.
128
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.
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 Section3.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.
130
API v1
You can use a cURL request similar to the following example for the bulk delete.
An HTTP request for the bulk delete is similar to the following example.
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.
131
API v1
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.
132
API v1
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.
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.
133
API v1
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.
134
API v1
135
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:
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:
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 Section5.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.
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.
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.
137
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:
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.
138
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 Section5.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/.
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 Section13.3.2, CORS headers for objects [142].
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:
139
API v1
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
X-Container-Meta-Access-Control-Expose-Headers
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 Section5.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 Example13.13, Test CORS page [141].
140
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 containers X-Container-Meta-Access-Control-Allow-Origin header, using a request similar to the following example.
141
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>
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.
142
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 HTTPheaders
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 HTTPmethod
will be used when the actual request is made.
Origin
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.
143
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.
144
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.
145