diff --git a/openstack-object-storage-dev/pom.xml b/openstack-object-storage-dev/pom.xml index 809a7c7..8326c01 100644 --- a/openstack-object-storage-dev/pom.xml +++ b/openstack-object-storage-dev/pom.xml @@ -50,7 +50,7 @@ com.rackspace.cloud.api clouddocs-maven-plugin - 1.5.2 + 1.7.2 goal1 @@ -90,24 +90,11 @@ + target/docbkx/webhelp/openstack-object-storage + 1.0 + bk-objectstorage-devguide-1.0 - - - - - - - - - - - - - + diff --git a/openstack-object-storage-dev/src/docbkx/object-api-create-website.xml b/openstack-object-storage-dev/src/docbkx/object-api-create-website.xml new file mode 100644 index 0000000..b842c9a --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-create-website.xml @@ -0,0 +1,128 @@ + + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ Create Static Website + You can use your swift account to create a static website. + This mode is normally only active for anonymous requests. To + use it with authenticated requests, set the header + X-Web-Mode to TRUE on the + request. The staticweb filter should be added to + the pipeline in your /etc/swift/proxy-server.conf + file just after any auth middleware. Beneath the pipeline, the + staticweb middleware configuration must be + added. For example: + + Your publicly readable containers will be checked for two + headers, X-Container-Meta-Web-Index and + X-Container-Meta-Web-Error. (The latter + header is discussed below, under Set + Error Pages for Static Website.) With + X-Container-Meta-Web-Index, you determine the + index file (or default page served, such as + index.html) displays your website. When + someone initially enters your site, they don't have to specify + the index file; index.html file displays automatically. If you + create sub-directories for your site--which you do by creating + pseudo-directories in your container--the index page displays + by default for each sub-directory. If your pseduo-directory + does not have a file with the same name as your index file, + visits to the sub-directory return a 404 error. + You also have the option of displaying a list of files in + your pseudo-directory instead of a web page. You do this by + setting the X-Container-Meta-Web-Listings header + to TRUE. You may add style to your file listing + by setting X-Container-Meta-Web-Listings-CSS: to + a stylesheet (i.e., lists.css). +
+ Static Web Middleware through swift + + Make Container Publicly Readable + Make the container publicly readable. Once the + container is publicly readable, you may access your + objects directly, but you will need to set the index + file to browse the main site URL and its + sub-directories. + swift post -r '.r:*' container + + + + Set Site Index File + Set the index file. In this case, + index.html is the default file + displayed when the site displays. + swift post -m 'web-index:index.html' container + + + + Enable File Listing + Turn on file listing. If you do not set the index + file, list the objects in the container. Instructions + on styling the list with the CSS follow. + swift post -m 'web-listings: true' container + + + + Enable CSS for File Listing + Style the file listing. + + +
+ + +
+ Set Error Pages for Static Website + You can create and set custom error pages for visitors + to your website; currently, only 401 (Unauthorized) and + 404 (Not Found) errors are supported. To do this, set the + metadata header, X-Container-Meta-Web-Error. + Error pages are served with the <status> code + pre-pended to the name of the error page you set. For + instance, if you set + X-Container-Meta-Web-Error to + error.html, 401 errors will display the + page 401error.html. Similarly, 404 errors + will display 404error.html. You must have + both of these pages created in your container when you set + the X-Container-Meta-Web-Error metadata, or + your site will display generic error pages. + Set the X-Container-Meta-Web-Error metadata + once for your entire static website. + + Set Error Pages for Static Website Request + + + Any 2xx response indicates success. + +
+
diff --git a/openstack-object-storage-dev/src/docbkx/object-api-dochistory.xml b/openstack-object-storage-dev/src/docbkx/object-api-dochistory.xml new file mode 100644 index 0000000..d049f7e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-dochistory.xml @@ -0,0 +1,41 @@ + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> + + Document Change History + This version of the guide was forked from the Rackspace Cloud Files Developer + Guide. + + + + + + + diff --git a/openstack-object-storage-dev/src/docbkx/object-api-general.xml b/openstack-object-storage-dev/src/docbkx/object-api-general.xml index 27b753b..a989209 100644 --- a/openstack-object-storage-dev/src/docbkx/object-api-general.xml +++ b/openstack-object-storage-dev/src/docbkx/object-api-general.xml @@ -31,235 +31,163 @@ format="SVG" scale="60"/> xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ch_object-storage-dev-general-api"> General API Information - - API Operations Reference Summary - Storage Accounts - - - - Verb - URI - Description - - - - - &GET; - /account - List containers - - - &HEAD; - account - Retrieve account metadata - - - - Storage Containers - - - - Verb - URI - Description - - - - - &GET; - /account/container - List objects - - - &PUT; - /account/container - Create container - - - &DELETE; - /account/container - Delete container - - - &HEAD; - /account/container - Retrieve container metadata - - - - Storage Objects - - - - Verb - URI - Description - - - - - &GET; - /account/container/object - Retrieve object - - - &PUT; - /account/container/object - Create/Update Object - - - &PUT; - /account/container/object - Chunked transfer encoding - - - &DELETE; - /account/container/object - Delete container - - - &HEAD; - /account/container/object - Retrieve object metadata - - - &POST; - /account/container/object - Update object metadata - - -
Authentication - Client authentication is provided via a ReST interface using the &GET; - method, with v1.0 supplied as the path. Additionally, two headers are required, - X-Auth-User and X-Auth-Key with values for the username and API - Access Key respectively. - Each ReST request against the OpenStack Object Storage system requires the inclusion of - a specific authorization token HTTP x-header, defined as X-Auth-Token. - Clients obtain this token, along with the Cloud Servers API URL, by first using an - authentication service and supplying a valid username and API access key. + Client authentication is provided via a ReST interface + using the &GET; method, with v1.0 supplied as + the path. Additionally, two headers are required, + X-Auth-User and X-Auth-Key + with values for the username and API Access Key + respectively. + Each ReST request against the OpenStack Object Storage + system requires the inclusion of a specific authorization + token HTTP x-header, defined as X-Auth-Token. + Clients obtain this token, along with the Cloud Servers + API URL, by first using an authentication service and + supplying a valid username and API access key. Request - - To authenticate, you must supply your username and API access key in x-headers: - + To authenticate, you must supply your username and + API access key in x-headers: - Use your OpenStack Object Storage (Swift) username as the username for the API. - Place it in the X-Auth-User x-header. + Use your OpenStack Object Storage + (Swift) username as the username for the + API. Place it in the + X-Auth-User x-header. + - Obtain your API access key from authentication service you chose when - installing. You have some options for auth, including tempauth (which is - included with Swift), swauth (an auth service for Swift as WSGI middleware that uses - Swift itself as a backing store that is provided via download from Github), - the OpenStack Identity Service (project named Keystone), or you can use your own - authentication system. Place your access key in the X-Auth-Key x-header. + Get your API access key from + authentication service you chose when + installing. You have some options for + auth, including tempauth (which is + included with Swift), swauth (an auth + service for Swift as WSGI middleware that + uses Swift itself as a backing store that + is provided via download from Github), the + OpenStack Identity Service (project named + Keystone), or you can use your own + authentication system. Place your access + key in the X-Auth-Key + x-header. - Authentication Request - - GET /v1.0 HTTP/1.1 - Host: auth.api.yourcloud.com - X-Auth-User: jdoe - X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89 - + Authentication HTTP Request + - Response - When authentication is successful, an HTTP status 204 (No Content) is returned with - the X-Storage-Url and - X-Auth-Token headers. Any 2xx response is a good response. - For example, a 202 response means the request has been accepted. - Also, additional X- headers - may be returned. These additional headers are related to other Rackspace services and can - be ignored. An HTTP status of 401 (Unauthorized) is returned upon authentication failure. - All subsequent container/object operations against OpenStack Object Storage should be made - against the URI specified in X-Storage-Url and must include the X-Auth-Token - header. + Response + When authentication is successful, an HTTP status + 204 (No Content) is returned with the + X-Storage-Url and + X-Auth-Token headers. Any 2xx + response is a good response. For example, a 202 + response means the request has been accepted. Also, + additional X- headers may be returned. + These additional headers are related to other + Rackspace services and can be ignored. An HTTP status + of 401 (Unauthorized) is returned upon authentication + failure. All subsequent container/object operations + against OpenStack Object Storage should be made + against the URI specified in + X-Storage-Url and must include the + X-Auth-Token header. - Authentication Response - - HTTP/1.1 204 No Content - Date: Mon, 12 Nov 2010 15:32:21 GMT - Server: Apache - X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_34 - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Length: 0 - Content-Type: text/plain; charset=UTF-8 - + Authentication HTTP Response + - The X-Storage-Url will need to be parsed and used in the - connection and request line of all subsequent requests against Object Storage. In the example - response above, users connecting to OpenStack Object Storage would send most - container/object requests with a host header of storage.swiftdrive.com and - the request line's version and account as /v1/CF_xer7_34. Note that - authentication tokens are valid for a 24 hour period for many authentication configurations. + The X-Storage-Url will need to be + parsed and used in the connection and request line of + all subsequent requests against Object Storage. In the + example response above, users connecting to OpenStack + Object Storage would send most container/object + requests with a host header of + storage.swiftdrive.com and the + request line's version and account as + /v1/CF_xer7_34. Note that + authentication tokens are valid for a 24 hour period + for many authentication configurations.
- +
Overview of API Operations - The OpenStack Object Storage API is implemented as a set of ReSTful (Representational State Transfer) - web services. All authentication and container/object operations can be performed with - standard HTTP calls. See the Wikipedia - article on ReST for more information - The following constraints apply to the ReST API's HTTP requests: + The OpenStack Object Storage API is implemented as a set + of ReSTful (Representational State Transfer) web services. + All authentication and container/object operations can be + performed with standard HTTP calls. See the Wikipedia article on ReST for more + information + The following constraints apply to the ReST API's HTTP + requests: - Maximum number of HTTP headers per request: 90 + Maximum number of HTTP headers per request: + 90 - Maximum length of all HTTP headers: 4096 bytes + Maximum length of all HTTP headers: 4096 + bytes - Maximum length per HTTP request line: 8192 bytes + Maximum length per HTTP request line: 8192 + bytes - Maximum length of HTTP request: 5 gigabytes + Maximum length of HTTP request: 5 + gigabytes - Maximum length of container name: 256 bytes + Maximum length of container name: 256 + bytes Maximum length of object name: 1024 bytes - Container and object names should be properly URL-encoded prior to interacting with the - ReST interface (the language APIs handle URL encoding/decoding) and the container - and object names must be UTF-8 encoded. The length restrictions should be checked - against the URL-encoded string. - Each ReST request against the OpenStack Object Storage system requires the inclusion of a specific - authorization token HTTP header defined as X-Auth-Token. - Clients obtain this token, along with the OpenStack Object Storage URLs, by first using the Authentication - service and supplying a valid Username and API Access Key. + Container and object names should be properly + URL-encoded prior to interacting with the ReST interface + (the language APIs handle URL encoding/decoding) and the + container and object names must be UTF-8 encoded. The + length restrictions should be checked against the + URL-encoded string. + Each ReST request against the OpenStack Object Storage + system requires the inclusion of a specific + authorization token HTTP header + defined as X-Auth-Token. Clients obtain this + token, along with the OpenStack Object Storage URLs, by + first using the Authentication service and supplying a + valid Username and API Access Key. - The ReST service identified with X-Storage-Url is used for managing the data stored - in the system. Example operations are creating containers and uploading objects. + The ReST service identified with + X-Storage-Url is used for managing the + data stored in the system. Example operations are creating + containers and uploading objects. - In the following sections, the purpose of each HTTP method depends upon which service the - call is made against. For example, a &PUT; request against X-Storage-Url can be - used to create a container or upload an - object. - The language-specific APIs mask this system separation from the programmer. They simply - create a container and mark it public and it handles calling out to the - appropriate back-end services using the appropriate ReST API. + In the following sections, the purpose of each HTTP + method depends upon which service the call is made + against. For example, a &PUT; request against + X-Storage-Url can be used to create a + container or upload an + object. + The language-specific APIs mask this system separation + from the programmer. They simply create a container and + mark it public and it handles calling + out to the appropriate back-end services using the + appropriate ReST API. - All requests to authenticate and operate against OpenStack Object Storage are performed using SSL - over HTTP (HTTPS) on TCP port 443. + All requests to authenticate and operate against + OpenStack Object Storage are performed using SSL over + HTTP (HTTPS) on TCP port 443. - +
+ diff --git a/openstack-object-storage-dev/src/docbkx/object-api-overview.xml b/openstack-object-storage-dev/src/docbkx/object-api-overview.xml index d8e75c3..df678c8 100644 --- a/openstack-object-storage-dev/src/docbkx/object-api-overview.xml +++ b/openstack-object-storage-dev/src/docbkx/object-api-overview.xml @@ -1,5 +1,5 @@ - @@ -25,29 +25,33 @@ format="SVG" scale="60"/> '> ]> - Overview - OpenStack Object Storage is an affordable, redundant, scalable, and dynamic storage - service offering. The core storage system is designed to provide a safe, secure, - automatically re-sizing and network-accessible way to store data. You can store an - unlimited quantity of files and each file can be as large as 5 gigabytes, plus with - large object creation, you can upload and store objects of virtually any size. - - OpenStack Object Storage allows users to store and retrieve files and content via a simple - Web Service inteface (ReST: Representational State Transfer). There are also - language-specific APIs that utilize the ReSTful API but make it much easier for - developers to integrate into their applications. + OpenStack Object Storage is an affordable, redundant, + scalable, and dynamic storage service offering. The core + storage system is designed to provide a safe, secure, + automatically re-sizing and network-accessible way to store + data. You can store an unlimited quantity of files and each + file can be as large as 5 GBs, plus with large object + creation, you can upload and store objects of virtually any + size. + OpenStack Object Storage allows users to store and retrieve + files and content through a simple Web Service interface + (ReST: Representational State Transfer). There are also + language-specific APIs that utilize the ReSTful API but make + it much easier for developers to integrate into their + applications. For more details on the OpenStack Object Storage service, please refer to http://swift.openstack.org - We welcome feedback, comments, and bug reports at http://bugs.launchpad.net/swift. - + We welcome feedback, comments, and bug reports at http://bugs.launchpad.net/swift.
Intended Audience This guide is intended to assist software developers who want to develop applications @@ -72,32 +76,5 @@ format="SVG" scale="60"/> its native format. For example, the Java API includes JavaDocs and the C#/.NET API includes a CHM file. -
- -
- Document Change History - This version of the Developer Guide was forked from the Rackspace Cloud Files Developer - Guide. - - - - - - -
-
- Additional Resources - You can download the most current version of this document from the OpenStack Docs - website at - http://docs.openstack.org. - - If you would like more information about the Rackspace implementation of - the OpenStack Object Storage service, visit this address: - - http://www.rackspacecloud.com/cloud_hosting_products/files. Related documents are - available at the same site, as are links to Rackspace's official support channels, including - knowledge base articles, forums, phone, chat, and email. -
- + diff --git a/openstack-object-storage-dev/src/docbkx/object-api-resources.xml b/openstack-object-storage-dev/src/docbkx/object-api-resources.xml new file mode 100644 index 0000000..a133042 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-resources.xml @@ -0,0 +1,44 @@ + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> + + Additional Resources + You can download the most current version of this document from the OpenStack Docs + website at + http://docs.openstack.org. + For more information about the Rackspace implementation of + the OpenStack Object Storage service, see: + + http://www.rackspacecloud.com/cloud_hosting_products/files. Related documents are + available at the same site, as are links to Rackspace's official support channels, including + knowledge base articles, forums, phone, chat, and email. + + diff --git a/openstack-object-storage-dev/src/docbkx/object-api-storage-container-svc.xml b/openstack-object-storage-dev/src/docbkx/object-api-storage-container-svc.xml new file mode 100644 index 0000000..7270ae4 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-storage-container-svc.xml @@ -0,0 +1,501 @@ + + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ Storage Container Services + You can perform the following operations for + containers: + + + + Verb + URI + Description + + + + + &GET; + /account/container + Lists objects. + + + &PUT; + /account/container + Creates a container. + + + &DELETE; + /account/container + Deletes a container. + + + &HEAD; + /account/container + Gets container metadata. + + + + All operations follow this format: + + Storage Container Services HTTP Request + METHOD /v1/<account>/<container> HTTP/1.1 + +
+ List Objects + &GET; operations against a storage container name are + performed to retrieve a list of objects stored in the + container. Additionally, there are a number of optional + query parameters that can be used to refine the list + results. + A request with no query parameters will return the full + list of object names stored in the container, up to 10,000 + names. Optionally specifying the query parameters will + filter the full list and return a subset of + objects. + + Query Parameters + + limit + + For an integer value + n + , limits the number of + results to at most + n + values. + + + + marker + + Given a string value + x + , return object names greater + in value than the specified marker. + + + + end_marker + + Given a string value + x + , return object names less in + value than the specified marker. + + + + prefix + + For a string value + x + , causes the results to be + limited to object names beginning with the + substring + x + . + + + + format + + Specify either json or + xml to return the respective + serialized response. + + + + delimiter + + For a character + c + , return all the object names + nested in the container (without the need for + the directory marker objects). + + + + path + + For a string value + x + , return the object names + nested in the pseudo path. Equivalent to + setting delimiter to '/' and prefix to the + path with a '/' on the end. + + + + + List Objects HTTP Request + + + A list of objects is returned in the response body, one + object name per line. A 204 (No Content) HTTP return code + will be passed back if the container is empty. If the + container does not exist, a 404 code will return. If an + incorrect account is specified, the HTTP return code will + be 404 (Not Found). + + List Objects HTTP Response + + +
+ Serialized List Output + If a format=xml or + format=json argument is appended to + the storage account URL, the service will serve + extended object information serialized in the chosen + format. Other than the ?format=xml|json + parameter, it will return the same status/errors + codes. The sample responses below are formatted for + readability. + + Get Objects Details HTTP and JSON + Request + + + + Get Objects Details HTTP and JSON Response + + + + + Objects Details Request: XML + + + + Objects Details Request: XML + + + +
+
+ Controlling a Large List of Objects + The system returns a maximum of 10,000 object names + per request. To retrieve subsequent object names, + another request must be made with the 'marker' + parameter. The marker indicates where the last list + left off and the system returns object names greater + than this marker, up to 10,000 again. Note that the + ‘marker’ value should be URL encoded prior to sending + the HTTP request. + If 10,000 is larger than desired, a 'limit' + parameter may be given. + If the number of object names returned equals the + limit given (or 10,000 if no limit is given), it can + be assumed there are more object names to be listed. + If the container name list is exactly divisible by the + limit, the last request has no content. + + List Large Number of Objects + For an example, let's use a listing of five + object names: + gala +grannysmith +honeycrisp +jonagold +reddelicious + We'll use a limit of two to show how things + work: + + Because we received two items back, we can + assume there are more object names to list. So, we + make another request with a marker of the last + item returned: + + Again we have two items returned; there might be + more: + + Now we received less than the limit number of + object names, indicating that we have the complete + list. + By using end_marker we can limit + the result set to object names less than the given + value. + + +
+
+ Pseudo-Hierarchical Folders and Directories + + Although you cannot nest directories in OpenStack + Object Storage, you can simulate a hierarchical + structure within a single container by adding forward + slash characters (/) in the object + name. To navigate the pseudo-directory structure, you + may use the delimiter query parameter. + See the below examples for an illustration. + + In the example below, the objects reside in a + container called backups. Within that + container, the objects are organized in a + pseudo-directory called photos. Keep + in mind that the container name is not displayed + in the example, but that it is a part of the + object URLs. For instance, the URL of the picture + me.jpg is + https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg. + + + + List Pseudo-Hierarchical Folders/Directories + Request + To display a list of all the objects in the + storage container, use &GET; without a + delimiter or prefix. + GET /v1/AccountString/backups + The system returns status code 200 (OK) and the + requested list of the objects. + photos/animals/cats/persian.jpg +photos/animals/cats/siamese.jpg +photos/animals/dogs/corgi.jpg +photos/animals/dogs/poodle.jpg +photos/animals/dogs/terrier.jpg +photos/me.jpg +photos/plants/fern.jpg +photos/plants/rose.jpg + + Use + the delimiter parameter to limit the displayed + results. Any character may be used as a delimiter. + However, to use delimiter with + pseudo-directories, use the parameter slash + (/). + GET /v1/AccountString/backups?delimiter=/ + The system returns status code 200 (OK) and the + requested matching objects. Because we use the + slash, only the pseudo-directory + photos/ displays. Keep in mind + that the returned values from a slash + delimiter query are not real + objects. They have a content-type of + application/directory and are in a subdir section + of json and xml results. + photos/ + Use the prefix parameter with the + delimiter parameter to view the + objects inside a pseudo-directory, including + further nested pseudo-directories. + GET /v1/AccountString/backups?prefix=photos/&delimiter=/ + The system returns status code 200 (OK) and the + objects and pseudo-directories within the top + level pseudo-directory. + photos/animals/ +photos/me.jpg +photos/plants/ + There is no limit to the amount of nested + pseudo-directories you can create. In order to + navigate through them, use a longer + prefix parameter coupled with the + delimiter parameter. In the + sample output below, there is a pseudo-directory + called dogs within the + pseudo-directory animals. In order to + navigate directly to the files contained within + dogs, enter the below command. + GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ + The system returns status code 200 (OK) and the + objects and pseudo-directories within the nested + pseudo-directory. + photos/animals/dogs/corgi.jpg +photos/animals/dogs/poodle.jpg +photos/animals/dogs/terrier.jpg + +
+ + +
+
+ Create Container + &PUT; operations against a storage container are used to + create that container. + Containers are storage compartments for your data. The + URL encoded name must be less than 256 bytes and cannot + contain a forward slash '/' character. + Containers can be assigned custom metadata by including + additional HTTP headers on the &PUT; request. The custom + metadata is assigned to a container via HTTP headers + identified with the X-Container-Meta- prefix. + + + Create Container HTTP Request + + + No content is returned. A status code of 201 (Created) + indicates that the container was created as requested. + Container &PUT; requests are idempotent and a code of 202 + (Accepted) is returned when the container already existed. + If you request a &PUT; to a container with an + X-Container-Meta- prefix in the header, + your &GET;/&HEAD; request responses carry the metadata + prefix from the container in subsequent requests. + + Create Container HTTP Response + + + Using custom container metadata, you can create + information in the header to effectively "tag" a container + with metadata. The container metadata restrictions are the + same as object metadata: you can have 4096 bytes maximum + overall metadata, 90 distinct metadata items at the most. + Each may have a 128 character name length with a 256 max + value length each. Any valid UTF-8 http header value is + allowed for metadata, however we recommend that you + URL-encode any non-ASCII values using a "%" symbol, + followed by the two-digit hexadecimal representation of + the ISO-Latin code for the character. + + + Container Create Container with Metadata HTTP Request + + + No content is returned. A status code of 201 (Created) + indicates that the container was created as requested. + Container &PUT; requests are idempotent and a code of 202 + (Accepted) is returned if the container existed prior to + the request. If you request a &PUT; to a container with an + X-Container-Meta- prefix in the header, + your &GET;/&HEAD; request responses carry the metadata + prefix from the container in subsequent requests. + + Create Container with Metadata HTTP Response + + +
+
+ Delete Container + &DELETE; operations against a storage container + permanently remove it. The container must be empty before + it can be deleted. + A &HEAD; request against the container can be used to + determine if it contains any objects. + + Delete Container HTTP Request + + + + No content is returned. A status code of 204 (No + Content) indicates success, 404 (Not Found) is returned if + the requested container was not found, and a 409 + (Conflict) if the container is not empty. No response body + is generated. + + Delete Container HTTP Response + + +
+
+ Get Container Metadata + &HEAD; operations against a storage container are used + to determine the number of objects, and the total bytes of + all objects stored in the container. Since the storage + system is designed to store large amounts of data, care + should be taken when representing the total bytes response + as an integer; when possible, convert it to a 64-bit + unsigned integer if your platform supports that primitive + type. + + Get Container Metadata HTTP Request + + + The HTTP return code will be 204 (No Content) if the + container exists, and 404 (Not Found) if it does not. The + object count and utilization are returned in the + X-Container-Object-Count and + X-Container-Bytes-Used headers + respectively. + + Get Container Metadata HTTP Response + + +
+
+ Create or Update Container Metadata + You may create any custom or arbitrary metadata headers + as you find useful. They must, however, take the format + X-Container-Meta-. + To create or update the arbitrary container metadata, + use the &POST; query. Subsequent requests of the same + key/value pair overwrites the previous value. + + Update Container Metadata HTTP Request + + + No response body is returned. A status code of 204 (No + Content) indicates success; status 404 (Not Found) is + returned when the requested container does not exist. + + Update Container Metadata HTTP Response + + + To confirm your metadata changes, perform a &HEAD; + request on the container. Do not send the metadata in your + &HEAD; request. + + View Container Metadata HTTP Request + + + + View Container Metadata HTTP Response + + + +
+
+ Delete Container Metadata + To delete a metadata header send an empty value for that + particular header, such as + X-Container-Meta-Book:. + If the tool you're using to communicate with Object + Storage doesn't support sending empty headers (older + versions of curl) send the header + "X-Remove-Container-Meta-name: + arbitrary value". For + example, send a header like + X-Remove-Container-Meta-Book: x. The + value (x in this example) is + ignored. + + Delete Container Metadata HTTP Request + + No response body is returned. A status code of 204 + (No Content) indicates success. + +
+
diff --git a/openstack-object-storage-dev/src/docbkx/object-api-storage-object-svc.xml b/openstack-object-storage-dev/src/docbkx/object-api-storage-object-svc.xml new file mode 100644 index 0000000..a6755b4 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-storage-object-svc.xml @@ -0,0 +1,701 @@ + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ Storage Object Services + An object represents the data and any metadata for the files + stored in the system. Through the ReST interface, metadata for + an object can be included by adding custom HTTP headers to the + request and the data payload as the request body. Objects + cannot exceed 5GB and must have names that do not exceed 1024 + bytes after URL encoding. However, objects larger than 5GB can + be segmented and then concatenated together so that you can + upload 5 GB segments and download a single concatenated + object. You can work with the segments and manifests directly + with HTTP requests. + + + + Verb + URI + Description + + + + + &GET; + /account/container/object + Gets object details. + + + &PUT; + /account/container/object + Creates or updates object. + + + &PUT; + /account/container/object + Chunked transfer encoding + + + &DELETE; + /account/container/object + Deletes container. + + + &HEAD; + /account/container/object + Gets object metadata. + + + &POST; + /account/container/object + Updates object metadata. + + + +
+ Get Object Details + &GET; operations against an object are used to retrieve + the object's data. + Note that you can perform conditional &GET; requests by + using certain HTTP headers as documented in RFC 2616. + OpenStack Object Storage supports the following + headers: + RFC 2616: http://www.ietf.org/rfc/rfc2616.txt + + + + If-Match + + + If-None-Match + + + If-Modified-Since + + + If-Unmodified-Since + + + It is also possible to fetch a portion of data using the + HTTP Range header. At this time, OpenStack + Object Storage does not support the full specification for + Range but basic support is provided. + OpenStack Object Storage only allows a single range that + includes OFFSET and/or LENGTH. We support a sub-set of + Range and do not adhere to the full + RFC-2616 specification. We support specifying + OFFSET-LENGTH where either OFFSET or LENGTH can be + optional (not both at the same time). The following are + supported forms of the header: + + + Range: bytes=-5 - last five bytes + of the object + + + Range: bytes=10-15 - the five bytes + after a 10-byte offset + + + Range: bytes=32- - all data after + the first 32 bytes of the object + + + + Get Object Details HTTP Request + + + The object's data is returned in the response body. + Object metadata is returned as HTTP headers. A status of + 200 (Ok) indicates success; status 404 (Not Found) is + returned if no such object exists. + + Get Object Details HTTP Response + + [ ... ] + +
+
+ Create or Update Object + &PUT; operations are used to write, or overwrite, an + object's content and metadata. + You can ensure end-to-end data integrity by including an + MD5 checksum of your object's data in the ETag header. You + are not required to include the ETag header, but it is + recommended to ensure that the storage system successfully + stored your object's content. + You can cause an object to expire after a certain date + by using the X-Delete-At or + X-Delete-After headers during an object + &PUT; operation. When Cloud Files detects one of these + headers, the system automatically stops serving that + object at the specified time and shortly after the + expiration date, it removes the object from the storage + system. + The HTTP response will include the MD5 checksum of the + data written to the storage system. If you do not send the + ETag in the request, you should compare the value returned + with your content's MD5 locally to perform the end-to-end + data validation on the client side. For segmented objects, + the ETag is the MD5 sum of the concatenated string of + ETags for each of the segments in the manifest, which only + offers change detection but not direct comparison. + Objects can be assigned custom metadata by including + additional HTTP headers on the &PUT; request. + The object can be created with custom metadata via HTTP + headers identified with the X-Object-Meta- + prefix. + + Create or Update Object HTTP Request + + [ ... ] + + No response body is returned. A status code of 201 + (Created) indicates a successful write; status 411 (Length + Required) 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) response is returned. + + Create or Update Object HTTP Response + + + +
+ Create Large Objects + Objects that are larger than 5GB must be segmented, + prior to upload. You then upload the segments like you + would any other object and create a manifest object + telling OpenStack Object Storage how to find the + segments of the large object. The segments remain + individually addressable, but retrieving the manifest + object streams all the segments concatenated. There is + no limit to the number of segments that can be a part + of a single large object. + + To ensure the download works correctly, you + must upload all the object segments to the same + container, ensure each object name has a common prefix + where their names sort in the order 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 the object segments + are in and <prefix> is the common prefix for all + the segments. + 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. + + Upload Segment of Large Object HTTP Request + + + + Upload Segment of Large Object + HTTP Response + s + + No response body is returned. A status code of 201 + (Created) indicates a successful write; status 411 + (Length Required) 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) response is + returned. + You can continue uploading segments like this + example shows, prior to uploading the manifest. + + Upload Next Segment of Large Object HTTP Request + + + + Upload Next Segment of Large Object + HTTP Response + w + + + Next, upload the manifest you created that indicates + the container the object segments reside within. Note + that uploading additional segments after the manifest + is created will cause the concatenated object to be + that much larger but you do not need to recreate the + manifest file for subsequent additional + segments. + + + Upload Manifest HTTP Request + + + + Upload Manifest HTTP Response + + + The response's Content-Type for a &GET; or &HEAD; on + the manifest will be the same as the Content-Type set + during the PUT request that created the manifest. You + can easily change the Content-Type by reissuing the + &PUT; request. +
+
+ Chunked Transfer Encoding + Users can upload data without needing to know in + advance the amount of data to be uploaded. Users can + do this by specifying an HTTP header of + Transfer-Encoding: chunked and not + using a Content-Length header. A good use + of this feature would be doing a DB dump, piping the + output through gzip, then piping the data directly + into OpenStack Object Storage without having to buffer + the data to disk to compute the file size. If users + attempt to upload more than 5GB with this method, the + server will close the TCP/IP connection after 5GB and + purge the customer data from the system. Users must + take responsibility for ensuring the data they + transfer will be less than 5GB or for splitting it + into 5GB chunks, each in its own storage object. If + you have files that are larger than 5GB and still want + to use Object Storage, you can segment them prior to + upload, upload them to the same container, and then + use a manifest file to allow downloading of a + concatenated object containing all the segmented + objects, concatenated as a single object. + + Upload Unspecified Quantity of Content + HTTP Request + + + + Upload Unspecified Quantity of Content + HTTP Response + + + +
+
+
+ Assigning CORS Headers to Requests + CORS is a specification that stands for Cross-Origin + Resource Sharing. It defines how browsers and servers + communicate across origins using HTTP headers, such as + those assigned by Cloud Files API requests. These headers + are supported with the Cloud Files API. You can read more + about the definition of the Access-Control- response + headers and Origin response header at www.w3.org/TR/access-control/. + + Access-Control-Allow-Credentials + + + Access-Control-Allow-Methods + + + Access-Control-Allow-Origin + + + Access-Control-Expose-Headers + + + Access-Control-Max-Age + + + Access-Control-Request-Headers + + + Access-Control-Request-Method + + + Origin + + + You can assign these headers to objects only. + + Assign CORS Header HTTP Request + In the example, the origin header is assigned that + indicates where the file came from. This allows you to + provide security that requests to your Cloud Files + repository are indeed from the correct + origination: + + +
+
+ Enabling File Compression with the Content-Encoding + Header + The Content-Encoding header allows a file to be + compressed without losing the identity of the underlying + media type of the file, for example, a video. + + Content-Encoding Header HTTP Request + In the example, the content-encoding header is + assigned with an attachment type that indicates how + the file should be downloaded: + + +
+
+ Enabling Browser Bypass with the Content-Disposition + Header + When an object is assigned the Content-Disposition + header you can override a browser's default behavior for a + file so that the download program saves the file rather + than displaying it using default browser settings. + + Content-Disposition Header HTTP Request + In the example, the content-encoding header is + assigned with an attachment type that indicates how + the file should be downloaded. + + +
+
+ Expiring Objects with the X-Delete-After and + X-Delete-At Headers + When an object is assigned either an + X-Delete-After or + X-Delete-At header when doing a &PUT; or + &POST; on the object, it is scheduled for deletion. This + feature is helpful for objects you do not want to + permanently store, such as log files, recurring full + backups of a dataset, or documents or images you know will + be outdated at a future 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 and calculates the amount of time from + now that you want the object to be deleted. The proxy + server that receives the request converts this header into + an X-Delete-At header and calculates the + deletion time using its current time plus the value given + in seconds. + For existing objects that you want to assign expiration + headers to, use the &POST; operation. + + Delete Object at HTTP Request + In the example, the X-Delete-At header + is assigned with a Unix Epoch timestamp in integer + form for Mon, 11 Jun 2012 15:38:25 GMT. Use http://www.epochconverter.com/ for example + timestamps and a batch converter. + + + + Delete Object after HTTP Request + In + this example, the X-Delete-After header + is assigned a value in seconds, equivalent to 10 days. + After this time, the object expires. + + + +
+ +
+ + Object Versioning + Object Versioning allows you to store multiple versions + of your content to recover from unintended overwrites. It + provides an easy method to implement version control which + can be used on any type of content. It is strongly + recommended that you put non-current objects in a + container apart from where the current versions exist. + Once you enable Object Versioning on a container (such as + a "current version" container), PUTs to existing objects + in that container copy the prior object to a separate + "non-current version" container. Each of the non-current + versions of an object has a time stamp appended to it, so + you know when it was created. + To enable Object Versioning, your cloud provider has to + set allow_versions to TRUE in + their container config. Then, create a container where + your non-current versions will be written. Next, set the + metadata X-Versions-Location header on the + container that holds the current versions of your objects. + Set the metadata header to point to the new non-current + version container you created. This is where your + non-current versions will be stored. Once this is done, + each object in your current-version container will have + Object Versioning enabled; changes to the objects + automatically create non-current versions in the separate + container. + Nothing is written to the non-current version container + when you initially &PUT; an object into the + current-version container. Only when you make edits to the + objects via &PUT; will you create non-current versions. + These non-current versions are labeled according to the + schema below. + + Naming Schema: Non-current versions + are assigned the name + <length><object_name>/<timestamp>, where + length is the 3-character zero-padded hexadecimal + character length of the <object_name> and + <timestamp> is when the it was initially created as + a current version. + Any return status in the 2xx range, such as 202 + (Accepted), notes success. Status codes in the 4xx or 5xx + range note failure. You should retry your request if you + receive an error. Please note, however, that if you have + specified a container that does not exist as your + non-current version container, a status of 412 + (Precondition Failed) returns when you edit the versioned + object. If you receive this error, check that the + container exists. + A &GET; to a versioned object returns the current + version of the object without having to do any request + redirects or metadata lookups. + A &POST; to a versioned object only updates the object's + metadata; it does not create a new version of the object. + In other words, new versions are only created when the + content of the object changes. + A &DELETE; to a versioned object removes the current + version of the object and replaces it with the next-most + current version, moving it from the non-current container + to the current. This next-most current version carries + with it any metadata last set on it. If want to completely + remove an object and you have five total versions of it, + you must &DELETE; it five times. + + A large-object manifest file cannot be versioned, + but it may point to versioned segments. + + To turn off Object Versioning on your current version + container, remove its X-Versions-Location + metadata by sending an empty key value. + + Object Versioning with cURL + Make sure a version-storing container exists, + creating it if necessary (this example names it + "versions"). Then create a container with the + X-Versions-Location header. In this + example, this container is named "current". You can + also add the X-Versions-Location header + to an existing container. In this example, the name of + the container is “versions”; the location for the + current version is the container "current". + Create a container named versions. + curl -i -XPUT -H "X-Auth-Token: <token>" http://<storage_url>/versions + Create a container named current with the + X-Versions-Location header that + references "versions". + + curl -i -XPUT -H "X-Auth-Token: <token>" \ + -H "X-Versions-Location: versions" http://<storage_url>/current + + Create an object (the first version): + + curl -i -XPUT --data-binary 1 -H "X-Auth-Token: <token>" \ + http://<storage_url>/current/myobject + + Now create a new version of that object: + + curl -i -XPUT --data-binary 2 -H "X-Auth-Token: <token>" \ + http://<storage_url>/current/myobject + + See a listing of the older versions of the object: + + curl -i -H "X-Auth-Token: <token>" \ + http://<storage_url>/versions?prefix=008myobject/ + + Now delete the current version of the object and see + that the older version is gone: + + curl -i -XDELETE -H "X-Auth-Token: <token>" \ + http://<storage_url>/current/myobject + curl -i -H "X-Auth-Token: <token>" \ + http://<storage_url>/versions?prefix=008myobject/ + + +
+ + + + +
+ Copy Object + Suppose you upload a file with the wrong object name or + content type, or you needed to move some objects to + another container. Without a server-side copy feature, you + would need to repeat uploading the same content and then + delete the existing object. With server-side object copy, + you can save the step of re-uploading the content and thus + also save the associated bandwidth charges, if any were to + apply. + There are two ways to copy an existing object to another + object in OpenStack Object Storage. One way is to do a + &PUT; to the new object (the target) location, but add the + “X-Copy-From” header to designate the + source of the data. The header value should be the + container and object name of the source object in the form + of “/container/object”. Also, the X-Copy-From + &PUT; requests require a Content-Length header, even if it + is zero (0). + + Object Copy Method 1 + + + The second way to do an object copy is similar. Do a + © to the existing object, and include the + “Destination” header to specify the target of the copy. + The header value is the container and new object name in + the form of “/container/object”. + + Object Copy Method 2 + + + With both of these methods, the destination container + must exist before attempting the copy. + If you wanted to move the object rather than copy it, + you need to send a &DELETE; request to the old object. A + move is simply a © + &DELETE;. All metadata is + preserved during the object copy. Note that you can set + metadata on the request to copy the object (either the + &PUT; or the ©) and the metadata will overwrite any + conflicting keys on the target (new) object. One + interesting use case is to copy an object to itself and + set the content type to a new value. This is the only way + to change the content type of an existing object. +
+
+ Delete Object + &DELETE; operations on an object are used to permanently + remove an object from the storage system (metadata and + data). + Deleting an object is processed immediately at the time + of the request. Any subsequent &GET;, &HEAD;, &POST;, or + &DELETE; operations will return a 404 (Not Found) error. + Objects with the X-Delete-At or + X-Delete-After header assigned are + deleted within one day of the expiration time and the + object is not served immediately after the expiration + time. Refer to Expiring Objects for more details. + + Object Delete HTTP Request + + + No response body is returned. A status code of 204 (No + Content) indicates success; status code 404 (Not Found) is + returned when the object does not exist. + + Object Delete HTTP Response + + +
+
+ Get Object Metadata + &HEAD; operations on an object are used to retrieve + object metadata and other standard HTTP headers. + The only required header to be sent in the request is + the authorization token. + + Get Object Metadata HTTP Request + + + No response body is returned. Metadata is returned as + HTTP headers. A status code of 200 (OK) indicates success; + status 404 (Not Found) is returned when the object does + not exist. + The &HEAD; return code for the object + is different from that of the container. &HEAD; requests + do not return a message body in the response, so anything + in the 2xx response code range notes success. When a + &HEAD; query is run against the container, it queries the + container databases, and it does not retrieve the content + of them, thus the 204 (No Content) return code. However, + when a &HEAD; query is run against the object, it returns + an "OK" response because it can view the content. In other + words, the object &HEAD; query has a container length, but + the container &HEAD; query has zero content length. + + Get Object Metadata HTTP Response + + +
+
+ Update Object Metadata + &POST; operations against an object name are used to set + and overwrite arbitrary key/value metadata or to assign + headers not already assigned such as + X-Delete-At or + X-Delete-After for expiring objects. You + cannot use the &POST; operation to change any of the + object's other headers such as Content-Type, + ETag, etc. It is not used to upload + storage objects (see &PUT;). Also refer to copying an object when + you need to update metadata or other headers such as + Content-Type or CORS headers. + Key names must be prefixed with + X-Object-Meta-. A &POST; request will + delete all existing metadata added with a previous + &PUT;/&POST;. + + Update Object Metadata HTTP Request + + + No response body is returned. A status code of 202 + (Accepted) indicates success; status 404 (Not Found) is + returned if the requested object does not exist. + + Update Object Metadata HTTP Response + + +
+
diff --git a/openstack-object-storage-dev/src/docbkx/object-api-storage-services.xml b/openstack-object-storage-dev/src/docbkx/object-api-storage-services.xml index e49c0d9..d501bf4 100644 --- a/openstack-object-storage-dev/src/docbkx/object-api-storage-services.xml +++ b/openstack-object-storage-dev/src/docbkx/object-api-storage-services.xml @@ -29,1780 +29,54 @@ format="SVG" scale="60"/> '> ]> - API Operations for Storage Services - The following section describes the ReST API for interacting with the storage component - of OpenStack Object Storage. All requests will be directed to the host and URL described in the - X-Storage-Url HTTP header obtained during successful authentication. - The following are some requirements for the use of the storage services: - - - Container names cannot exceed 256 bytes and cannot contain a '/' character - - - Object names cannot exceed 1024 bytes and have no character restrictions - - - Object and container names must be URL-encoded and UTF-8 encoded - - - - - The following sections describe the actions that may be performed within the - storage system. The first section addresses actions that can be taken on the account - level of the storage system. The second section addresses actions that may be performed - on containers. The third section addresses actions that may be performed on objects. - -
- Storage Account Services - The following operations can be performed at the account level of the URL. For - example, the URL for the requests below will end with the OpenStack Object Storage account - string: - - Storage Account HTTP Request: General Structure - - METHOD /v1/<account> HTTP/1.1 - - -
- List Containers - &GET; operations against the X-Storage-Url for an account - are performed to retrieve a list of existing storage containers ordered by name. The sort order for the name - is based on a binary comparison, a single built-in - collating sequence that compares string data using SQLite's memcmp() function, - regardless of text encoding. The following list describes the optional query parameters that are supported with this - request. - - Query Parameters - - limit - - For an integer value - n - , limits the number of results to - n - values. - - - - marker - - Given a string value - x - , return container names greater in value than the specified - marker. - - - - end_marker - - Given a string value - x - , return container names less in value than the specified - marker. - - - - format - - Specify either json or xml to return the respective - serialized response. - - - - At this time, a prefix query parameter is not supported at the account - level. - - Containers List Request - - GET /<api version>/<account> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - A list of containers is returned in the response body, one container per line. A 204 - (No Content) HTTP return code will be passed back if the account has no - containers. - - Containers List Response - - HTTP/1.1 200 Ok - Date: Thu, 07 Jun 2010 18:57:07 GMT - Server: Apache - Content-Type: text/plain; charset=UTF-8 - Content-Length: 32 - - - images - movies - documents - backups - - -
- Serialized List Output - If a format=xml or format=json argument is appended to - the storage account URL, the service will serve extended container information - serialized in the chosen format. The sample responses below are formatted for - readability. - - Containers Details Request: JSON - - GET /<api version>/<account>?format=json HTTP/1.1 - Host: storage.swiftdrive.com - Content-Length: 0 - X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 - - - - Containers Details Response: JSON - - HTTP/1.1 200 OK - Date: Tue, 25 Nov 2008 19:39:13 GMT - Server: Apache - Content-Type: application/json; charset=utf-8 - - - [ - {"name":"test_container_1", "count":2, "bytes":78}, - {"name":"test_container_2", "count":1, "bytes":17} - ] - - - - Containers Details Request: XML - - GET /<api version>/<account>?format=xml HTTP/1.1 - Host: storage.swiftdrive.com - Content-Length: 0 - X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 - - - - Containers Details Response: XML - - HTTP/1.1 200 OK - Date: Tue, 25 Nov 2008 19:42:35 GMT - Server: Apache - Content-Type: application/xml; charset=utf-8 - - - <?xml version="1.0" encoding="UTF-8"?> - - <account name="MichaelBarton"> - <container> - <name>test_container_1</name> - <count>2</count> - <bytes>78</bytes> - </container> - <container> - <name>test_container_2</name> - <count>1</count> - <bytes>17</bytes> - </container> - </account> - - -
-
- Controlling a Large List of Containers - The system returns a maximum of 10,000 container names per request. To - retrieve subsequent container names, another request must be made with the 'marker' - parameter. The marker indicates where the last list left off; the system returns - container names greater than this marker, up to 10,000 again. Note that the ‘marker’ - value should be URL-encoded prior to sending the HTTP request. - If 10,000 is larger than desired, use the 'limit' parameter. - If the number of container names returned equals the limit given (or 10,000 if no - limit is given), you may assume there are more container names. - - List Large Number of Containers - For example, let's use a listing of five container names - - apples - bananas - kiwis - oranges - pears - - We'll use a limit of two to show how things work: - - GET /<api version>/<account>?limit=2 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - apples - bananas - - Since we received two items back, we can assume there are more container names - to list, so we make another request with a marker of the last item returned: - - GET /<api version>/<account>?limit=2&marker=bananas - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - kiwis - oranges - - Again, two items are returned; there may be more: - - GET /<api version>/<account>?limit=2&marker=oranges - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - pears - - With this one-item response we received less than the limit number of container - names, indicating that this is the end of the list. - - By using end_marker we can limit the result set to - container names less than the given value. - - - GET /<api version><account>?end_marker=oranges - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - apples - bananas - kiwis - - -
-
-
- Retrieve Account Metadata - &HEAD; operations against an account are - performed to retrieve the number of containers and the total - bytes stored in OpenStack Object Storage for the account. This - information is returned in two custom headers, - X-Account-Container-Count and - X-Account-Bytes-Used. Since the storage system - is designed to store large amounts of data, care should be - taken when representing the total bytes response as an - integer; when possible, convert it to a 64-bit unsigned - integer if your platform supports that primitive - type. - - Account Metadata Request - - HEAD /<api version>/<account> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - The HTTP return code will be 204 (No Content) if the request succeeds. A 401 - (Unauthorized) will be returned for an invalid account or access key. - - Account Metadata Response - - HTTP/1.1 204 No Content - Date: Thu, 07 Jun 2010 18:57:07 GMT - Server: Apache - X-Account-Container-Count: 3 - X-Account-Bytes-Used: 323479 - - -
-
- Create/Update Account Metadata - - You can associate custom metadata headers with the account level - URI. These headers must take the format - X-Account-Meta-*. - - - To create or update an account metadata header use the &POST; query. - Subsequent requests for the same key/value pair overwrite the - previous value. - - - Update Account Metadata Request - - POST /<api version>/<account> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - X-Account-Meta-Book: MobyDick - X-Account-Meta-Subject: Whaling - - - - No response body is returned. A status code of 204 (No Content) - indicates success. - - - Update Account Metadata Response - - HTTP/1.1 204 No Content - Content-Length: 0 - Content-Type: text/html; charset=UTF-8 - Date: Sat, 09 Jun 2012 19:16:29 GMT - - - To confirm your metadata changes, perform a &HEAD; request on the - account. Do not send the metadata in your &HEAD; request. - - View Account Metadata Request - - HEAD /<api version>/<account> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - - View Account Metadata Response - - HTTP/1.1 204 No Content - X-Account-Meta-Book: MobyDick - X-Account-Meta-Subject: Whaling - X-Account-Object-Count: 5 - X-Timestamp: 1323466696.21566 - X-Account-Container-Count: 5 - X-Account-Bytes-Used: 46988 - Accept-Ranges: bytes - Content-Length: 0 - Date: Sat, 09 Jun 2012 19:16:59 GMT - - -
-
- Delete Account Metadata - To delete a metadata header send an empty value for that - particular header, e.g. X-Account-Meta-Book:. - If the tool you're using to communicate with Swift doesn't - support sending empty headers (e.g. older versions of curl) send - the header - "X-Remove-Account-Meta-name: arbitrary value", - e.g. X-Remove-Account-Meta-Book: x. The - value is ignored. - - Account Metadata Delete Request - -POST /<api version>/<account> HTTP/1.1 -Host: storage.clouddrive.com -X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb -X-Remove-Account-Meta-Book: x - - - No response body is returned. A status code of 204 (No Content) - indicates success. - - -
-
-
- Storage Container Services - This section documents the ReST operations that can be performed on containers. All - operations are valid HTTP request methods and will resemble this format: - - Storage Container HTTP Request: General Structure - - METHOD /v1/<account>/<container> HTTP/1.1 - - -
- List Objects - &GET; operations against a storage container name are performed to - retrieve a list of objects stored in the container. Additionally, there are a number of - optional query parameters that can be used to refine the list results. - A request with no query parameters will return the full list of object names stored - in the container, up to 10,000 names. Optionally specifying the query parameters will - filter the full list and return a subset of objects. - - Query Parameters - - limit - - For an integer value - n - , limits the number of results to at most - n - values. - - - - marker - - Given a string value - x - , return object names greater in value than the specified - marker. - - - - end_marker - - Given a string value - x - , return object names less in value than the specified - marker. - - - - prefix - - For a string value - x - , causes the results to be limited to object names beginning with - the substring - x - . - - - - format - - Specify either json or xml to return the respective - serialized response. - - - - delimiter - - For a character - c - , return all the object names nested in the container (without - the need for the directory marker objects). - - - - path - - For a string value - x - , return the object names nested in the pseudo path. Equivalent to setting delimiter to '/' and prefix to the path with a '/' on the end. - - - - - Objects List Request - - GET /<api version>/<account>/<container>[?parm=value] HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - A list of objects is returned in the response body, one object name per line. A 204 - (No Content) HTTP return code will be passed back if the container is empty. If the container - does not exist, a 404 code will return. If an incorrect account is specified, the HTTP return - code will be 404 (Not Found). - - Objects List Response - - HTTP/1.1 200 Ok - Date: Thu, 07 Jun 2010 18:50:19 GMT - Server: Apache - Content-Type: text/plain; charset=UTF-8 - Content-Length: 171 - - - kate_beckinsale.jpg - How To Win Friends And Influence People.pdf - moms_birthday.jpg - poodle_strut.mov - Disturbed - Down With The Sickness.mp3 - army_of_darkness.avi - the_mad.avi - - -
- Serialized List Output - If a format=xml or format=json argument is appended to - the storage account URL, the service will serve extended object information serialized - in the chosen format. Other than the ?format=xml|json parameter, it will return - the same status/errors codes. The sample responses below are formatted for - readability. - - Objects Details Request: JSON - - GET /<api version>/<account>/<container>?format=json HTTP/1.1 - Host: storage.swiftdrive.com - Content-Length: 0 - X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 - - - - Objects Details Response: JSON - - HTTP/1.1 200 OK - Date: Tue, 25 Nov 2008 19:39:13 GMT - Server: Apache - Content-Length: 387 - Content-Type: application/json; charset=utf-8 - - - [ - {"name":"test_obj_1", - "hash":"4281c348eaf83e70ddce0e07221c3d28", - "bytes":14, - "content_type":"application\/octet-stream", - "last_modified":"2009-02-03T05:26:32.612278"}, - {"name":"test_obj_2", - "hash":"b039efe731ad111bc1b0ef221c3849d0", - "bytes":64, - "content_type":"application\/octet-stream", - "last_modified":"2009-02-03T05:26:32.612278"}, - ] - - - - Objects Details Request: XML - - GET /<api version>/<account>/<container>?format=xml HTTP/1.1 - Host: storage.swiftdrive.com - X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 - - - - Objects Details Request: XML - - HTTP/1.1 200 OK - Date: Tue, 25 Nov 2008 19:42:35 GMT - Server: Apache - Content-Length: 643 - Content-Type: application/xml; charset=utf-8 - - - <?xml version="1.0" encoding="UTF-8"?> - - <container name="test_container_1"> - <object> - <name>test_object_1</name> - <hash>4281c348eaf83e70ddce0e07221c3d28</hash> - <bytes>14</bytes> - <content_type>application/octet-stream</content_type> - <last_modified>2009-02-03T05:26:32.612278</last_modified> - </object> - <object> - <name>test_object_2</name> - <hash>b039efe731ad111bc1b0ef221c3849d0</hash> - <bytes>64</bytes> - <content_type>application/octet-stream</content_type> - <last_modified>2009-02-03T05:26:32.612278</last_modified> - </object> - </container> - - -
-
- Controlling a Large List of Objects - The system returns a maximum of 10,000 object names per request. To retrieve - subsequent object names, another request must be made with the 'marker' parameter. The - marker indicates where the last list left off and the system returns object names - greater than this marker, up to 10,000 again. Note that the ‘marker’ value should be - URL encoded prior to sending the HTTP request. - If 10,000 is larger than desired, a 'limit' parameter may be given. - If the number of object names returned equals the limit given (or 10,000 if no - limit is given), it can be assumed there are more object names to be listed. If the - container name list is exactly divisible by the limit, the last request will simply - have no content. - - List Large Number of Objects - For an example, let's use a listing of five object names: - - gala - grannysmith - honeycrisp - jonagold - reddelicious - - We'll use a limit of two to show how things work: - - GET /<api version>/<account>/<container>?limit=2 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - gala - grannysmith - - Since we received two items back, we can assume there are more object names to - list. So, we make another request with a marker of the last item returned: - - GET /<api version>/<account>/<container>?limit=2&marker=grannysmith - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - honeycrisp - jonagold - - Again we have two items returned; there may be more: - - GET /<api version>/<account>/<container>?limit=2&marker=jonagold - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - reddelicious - - Now we received less than the limit number of object names, indicating that we - have the complete list. - - By using end_marker we can limit the result set to - object names less than the given value. - - - GET /<api version><account>/<container>?end_marker=jonagold - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - gala - grannysmith - honeycrisp - - -
-
- Pseudo-Hierarchical Folders/Directories - - Although you cannot nest directories in OpenStack Object Storage, you can simulate - a hierarchical structure within a single container by adding forward slash - characters (/) in the object name. To navigate the pseudo-directory - structure, you may use the delimiter query parameter. See the below examples - for an illustration. - - In the example below, the objects reside in a container called backups. - Within that container, the objects are organized in a pseudo-directory called photos. - Keep in mind that the container name is not displayed in the example, - but that it is a part of the object URLs. For instance, the URL of the - picture me.jpg is - https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg. - - - - Pseudo-Hierarchical Folders/Directories - - To display a list of all the objects in the storage container, use &GET; without a - delimiter or prefix. - - - GET /v1/AccountString/backups - - - The system returns status code 200 (OK) and the requested list of the objects. - - - photos/animals/cats/persian.jpg - photos/animals/cats/siamese.jpg - photos/animals/dogs/corgi.jpg - photos/animals/dogs/poodle.jpg - photos/animals/dogs/terrier.jpg - photos/me.jpg - photos/plants/fern.jpg - photos/plants/rose.jpg - - - - Use the delimiter parameter to limit the displayed results. Any character may be used - as a delimiter. However, to use delimiter with pseudo-directories, - use the parameter slash (/). - - - GET /v1/AccountString/backups?delimiter=/ - - - The system returns status code 200 (OK) and the requested matching objects. Because - we use the slash, only the pseudo-directory photos/ displays. - Keep in mind that the returned values - from a slash delimiter query are not real objects. They have a content-type of - application/directory and are in a subdir section of json and xml results. - - - photos/ - - - Use the prefix parameter with the delimiter parameter - to view the objects inside a pseudo-directory, including further nested - pseudo-directories. - - - GET /v1/AccountString/backups?prefix=photos/&delimiter=/ - - - The system returns status code 200 (OK) and the objects and pseudo-directories within - the top level pseudo-directory. - - - photos/animals/ - photos/me.jpg - photos/plants/ - - - There is no limit to the amount of nested pseudo-directories you can create. In order to - navigate through them, use a longer prefix parameter coupled with the - delimiter parameter. In the sample output below, there is a - pseudo-directory called dogs within the pseudo-directory animals. - In order to navigate directly to the files contained within dogs, enter - the below command. - - - GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ - - - The system returns status code 200 (OK) and the objects and pseudo-directories within - the nested pseudo-directory. - - - photos/animals/dogs/corgi.jpg - photos/animals/dogs/poodle.jpg - photos/animals/dogs/terrier.jpg - - -
- - -
-
- Create Container - &PUT; operations against a storage container are used to create that - container. - Containers are storage compartments for your data. The URL encoded name must be less - than 256 bytes and cannot contain a forward slash '/' character. - Containers can be assigned custom metadata by including additional HTTP headers on the - &PUT; request. The custom metadata is assigned to a container via HTTP headers identified - with the X-Container-Meta- prefix. - - - Container Create Request - - PUT /<api version>/<account>/<container> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - No content is returned. A status code of 201 (Created) indicates that the container - was created as requested. Container &PUT; requests are idempotent and a code - of 202 (Accepted) is returned when the container already existed. If you request a &PUT; to a - container with an X-Container-Meta- prefix in the header, your &GET;/&HEAD; - request responses carry the metadata prefix from the container in subsequent - requests. - - Container Create Response - - HTTP/1.1 201 Created - Date: Thu, 07 Jun 2007 18:50:19 GMT - Server: Apache - Content-Type: text/plain; charset=UTF-8 - - - Using custom container metadata, you can create information in the header to - effectively "tag" a container with metadata. The container metadata restrictions are the - same as object metadata: you can have 4096 bytes maximum overall metadata, 90 distinct - metadata items at the most. Each may have a 128 character name length with a 256 max value - length each. Any valid UTF-8 http header value is allowed for metadata, however we - recommend that you URL-encode any non-ASCII values using a "%" symbol, followed by the - two-digit hexadecimal representation of the ISO-Latin code for the character. - - - Container Create Request with Metadata - - PUT /<api version>/<account>/<container> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - X-Container-Meta-InspectedBy: JackWolf - - - No content is returned. A status code of 201 (Created) indicates that the container - was created as requested. Container &PUT; requests are idempotent and a code of 202 - (Accepted) is returned if the container existed prior to the request. If you request a &PUT; to a - container with an X-Container-Meta- prefix in the header, your &GET;/&HEAD; - request responses carry the metadata prefix from the container in subsequent - requests. - - Container Create Response - - HTTP/1.1 201 Created - Date: Thu, 07 Jun 2010 18:50:19 GMT - Server: Apache - Content-Type: text/plain; charset=UTF-8 - - -
-
- Delete Container - &DELETE; operations against a storage container permanently remove it. The - container must be empty before it can be deleted. - - A &HEAD; request against the container can be used to determine if it - contains any objects. - - Container Delete Request - - DELETE /<api version>/<account>/<container> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - - No content is returned. A status code of 204 (No Content) indicates success, 404 - (Not Found) is returned if the requested container was not found, and a 409 (Conflict) - if the container is not empty. No response body is generated. - - Container Delete Response - - HTTP/1.1 204 No Content - Date: Thu, 07 Jun 2010 18:57:07 GMT - Server: Apache - Content-Length: 0 - Content-Type: text/plain; charset=UTF-8 - - -
-
- Retrieve Container Metadata - &HEAD; operations against a storage - container are used to determine the number of objects, and - the total bytes of all objects stored in the - container. Since the storage system is designed to store - large amounts of data, care should be taken when - representing the total bytes response as an integer; when - possible, convert it to a 64-bit unsigned integer if your - platform supports that primitive type. - - Container Metadata Request - - HEAD /<api version>/<account>/<container> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - The HTTP return code will be 204 (No Content) if the container exists, and 404 (Not - Found) if it does not. The object count and utilization are returned in the - X-Container-Object-Count and X-Container-Bytes-Used headers - respectively. - - Container Metadata Response - - HTTP/1.1 204 No Content - Date: Wed, 11 Jul 2010 19:37:41 GMT - Content-type: text/html - X-Container-Object-Count: 7 - X-Container-Bytes-Used: 413 - X-Container-Meta-InspectedBy: JackWolf - - -
-
- Create/Update Container Metadata - - You may create any custom or arbitrary metadata headers as you find useful. They - must, however, take the format X-Container-Meta-. - - - To create or update the arbitrary container metadata, use the &POST; query. - Subsequent requests of the same key/value pair overwrites the previous value. - - - Update Container Metadata Request - - POST /<api version>/<account>/<container>/ HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - X-Container-Meta-Book: MobyDick - X-Container-Meta-Subject: Whaling - - - No response body is returned. A status code of 204 - (No Content) indicates success; status 404 (Not Found) is - returned when the requested container does not exist. - - Update Container Metadata Response - - HTTP/1.1 204 No Content - Date: Thu, 07 Mar 2012 20:42:51 GMT - Server: Apache - Content-Length: 0 - Content-Type: text/plain; charset=UTF-8 - - - To confirm your metadata changes, perform a &HEAD; request on the container. Do not send - the metadata in your &HEAD; request. - - View Container Metadata Request - - HEAD /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - - View Container Metadata Response - - HTTP/1.1 204 No Content - X-Container-Object-Count: 0 - X-Trans-Id: tx028b40d228534c759f4d5fa69f8cf7fd - X-Container-Meta-Book: MobyDick - X-Container-Meta-Subject: Whaling - Accept-Ranges: bytes - Date: Mon, 12 Mar 2012 16:40:20 GMT - Content-Length: 0 - X-Container-Bytes-Used: 0 - - - -
-
- Delete Container Metadata - To delete a metadata header send an empty value for - that particular header, such as - X-Container-Meta-Book:. - If the tool you're using to communicate with Object - Storage doesn't support sending empty headers (older versions - of curl) send the header - "X-Remove-Container-Meta-name: - arbitrary value". For example, - send a header like X-Remove-Container-Meta-Book: - x. The value (x in this example) - is ignored. - - Container Metadata Delete Request - -POST /<api version>/<account>/<container> HTTP/1.1 -Host: storage.clouddrive.com -X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb -X-Remove-Container-Meta-Book: x - - - No response body is returned. A status code of 204 (No Content) - indicates success. - - -
-
-
- Create Static Website - You may use your swift account to create a static website - on the World Wide Web. This mode is normally only active for - anonymous requests. If you want to use it with authenticated - requests, set the header X-Web-Mode to - TRUE on the request. The staticweb - filter should be added to the pipeline in your - /etc/swift/proxy-server.conf file just after any - auth middleware. Beneath the pipeline, the - staticweb middleware configuration must be added. - For example: - - [DEFAULT] - ... - - [pipeline:main] - pipeline = healthcheck cache tempauth staticweb proxy-server - - ... - - [filter:staticweb] - use = egg:swift#staticweb - # Seconds to cache container x-container-meta-web-* header values. - # cache_timeout = 300 - # You can override the default log routing for this filter here: - # set log_name = staticweb - # set log_facility = LOG_LOCAL0 - # set log_level = INFO - # set access_log_name = staticweb - # set access_log_facility = LOG_LOCAL0 - # set access_log_level = INFO - # set log_headers = False - - Your publicly readable containers will be checked for two - headers, X-Container-Meta-Web-Index and - X-Container-Meta-Web-Error. (The latter header is - discussed below, under Set Error Pages for Static Website.) - With X-Container-Meta-Web-Index, you determine the - index file (or default page served, such as - index.html) displays your website. When someone - initially enters your site, they don't have to specify the index - file; index.html file displays automatically. If you create - sub-directories for your site--which you do by creating - pseudo-directories in your container--the index page displays by - default for each sub-directory. If your pseduo-directory does - not have a file with the same name as your index file, visits to - the sub-directory return a 404 error. - - You also have the option of displaying a list of files in your - pseudo-directory instead of a web page. You do this by setting - the X-Container-Meta-Web-Listings header to - TRUE. You may add style to your file listing by setting - X-Container-Meta-Web-Listings-CSS: to a stylesheet - (i.e., lists.css). - -
- Static Web Middleware via swift - - Make Container Publicly Readable - - Make the container publicly readable. Once the container - is publicly readable, you may access your objects directly, but - you will need to set the index file to browse the main site - URL and its sub-directories. - - - swift post -r '.r:*' container - - - - - Set Site's Index File - Set the index file. In this case, index.html is the - default file displayed when the site displays. - - - swift post -m 'web-index:index.html' container - - - - - Enable File Listing - Turn on file listing. If you do not set the index file, list - the objects in the container. Instructions on styling the list - with the CSS follow. - - - swift post -m 'web-listings: true' container - - - - - Enable CSS for File Listing - Style the file listing. - - - swift post -m 'web-listings-css:listings.css' container - - -
- - -
- Set Error Pages for Static Website - - You may create and set custom error pages for visitors to your website; - currently, only 401 (Unauthorized) and 404 (Not Found) errors are supported. - To do this, set the metadata header, X-Container-Meta-Web-Error. - - - Error pages are served with the <status> code prepended to the name - of the error page you set. For instance, if you set - X-Container-Meta-Web-Error to error.html, - 401 errors will display the page 401error.html. Similarly, 404 errors - will display 404error.html. You must have both of these pages created - in your container when you set the X-Container-Meta-Web-Error - metadata, or your site will display generic error pages. - - - You need only set the X-Container-Meta-Web-Error metadata once - for your entire static website. - - - Set Error Pages for Static Website - - swift post -m 'web-error:error.html' container - - - - Any 2xx response indicates success. - -
-
- -
- Storage Object Services - An object represents the data and any metadata for the files stored in the - system. Through the ReST interface, metadata for an object can be included by adding - custom HTTP headers to the request and the data payload as the request body. Objects - cannot exceed 5GB and must have names that do not exceed 1024 bytes after URL - encoding. However, objects larger than 5GB can be segmented and then concatenated together so that you can upload 5 GB segments and download a single concatenated object. You can work with the segments and manifests directly with HTTP requests. -
- Retrieve Object - &GET; operations against an object are used to retrieve - the object's data. - Note that you can perform conditional &GET; requests by - using certain HTTP headers as documented in RFC 2616. - OpenStack Object Storage supports the following - headers: - RFC 2616: http://www.ietf.org/rfc/rfc2616.txt - - - - If-Match - - - If-None-Match - - - If-Modified-Since - - - If-Unmodified-Since - - - It is also possible to fetch a portion of data using the - HTTP Range header. At this time, OpenStack Object - Storage does not support the full specification for - Range but basic support is provided. OpenStack - Object Storage only allows a single range that includes OFFSET - and/or LENGTH. We support a sub-set of Range and - do not adhere to the full RFC-2616 specification. We support - specifying OFFSET-LENGTH where either OFFSET or LENGTH can be - optional (not both at the same time). The following are - supported forms of the header: - - - Range: bytes=-5 - last five bytes of the - object - - - Range: bytes=10-15 - the five bytes after - a 10-byte offset - - - Range: bytes=32- - all data after the - first 32 bytes of the object - - - - Retrieve Object Request - - GET /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - The object's data is returned in the response body. Object - metadata is returned as HTTP headers. A status of 200 (Ok) - indicates success; status 404 (Not Found) is returned if no - such object exists. - - Retrieve Object Response - - HTTP/1.1 200 Ok - Date: Wed, 11 Jul 2010 19:37:41 GMT - Server: Apache - Last-Modified: Fri, 12 Jun 2010 13:40:18 GMT - ETag: b0dffe8254d152d8fd28f3c5e0404a10 - Content-type: text/html - Content-Length: 512000 - - - [ ... ] - - -
-
- Create/Update Object - &PUT; operations are used to write, or overwrite, an - object's content and metadata. - You can ensure end-to-end data integrity by including an - MD5 checksum of your object's data in the ETag header. You are - not required to include the ETag header, but it is recommended - to ensure that the storage system successfully stored your - object's content. - You can cause an object to expire after a certain date by - using the X-Delete-At or - X-Delete-After headers during an object &PUT; - operation. When Cloud Files detects one of these headers, - the system automatically stops serving that object at the - specified time and shortly after the expiration date, it - removes the object from the storage system. - - The HTTP response will include the MD5 checksum of the - data written to the storage system. If you do not send the - ETag in the request, you should compare the value returned - with your content's MD5 locally to perform the end-to-end data - validation on the client side. For segmented objects, the ETag - is the MD5 sum of the concatenated string of ETags for each of - the segments in the manifest, which only offers change - detection but not direct comparison. - Objects can be assigned custom metadata by including - additional HTTP headers on the &PUT; request. - The object can be created with custom metadata via HTTP - headers identified with the X-Object-Meta- - prefix. - - Create/Update Object Request - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - ETag: 8a964ee2a5e88be344f36c22562a6486 - Content-Length: 512000 - X-Object-Meta-PIN: 1234 - - - [ ... ] - - - No response body is returned. A status code of 201 - (Created) indicates a successful write; status 411 (Length - Required) 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) response is returned. - - Create/Update Object Response - - HTTP/1.1 201 Created - Date: Thu, 07 Jun 2010 18:57:07 GMT - Server: Apache - ETag: d9f5eb4bba4e2f2f046e54611bc8196b - Content-Length: 0 - Content-Type: text/plain; charset=UTF-8 - - - -
- Large Object Creation - Objects that are larger than 5GB must be segmented, - prior to upload. You then upload the segments like you would - any other object and create a manifest object telling - OpenStack Object Storage how to find the segments of the - large object. The segments remain individually addressable, - but retrieving the manifest object streams all the segments - concatenated. There is no limit to the number of segments - that can be a part of a single large object. - - In order to ensure the download works correctly, you - must upload all the object segments to the same container, - ensure each object name has a common prefix where their - names sort in the order 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 the object segments are - in and <prefix> is the common prefix for all the - segments. - 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. - - Upload Segment of a Large Object - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - ETag: 8a964ee2a5e88be344f36c22562a6486 - Content-Length: 1 - X-Object-Meta-PIN: 1234 - - - s - - - No response body is returned. A status code of 201 - (Created) indicates a successful write; status 411 (Length - Required) 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) response is returned. - You can continue uploading segments like this example - shows, prior to uploading the manifest. - - Upload Next Segment of the Large Object - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - ETag: 8a964ee2a5e88be344f36c22562a6486 - Content-Length: 1 - X-Object-Meta-PIN: 1234 - - - w - - - - Next, upload the manifest you created that indicates the - container the object segments reside within. Note that - uploading additional segments after the manifest is created - will cause the concatenated object to be that much larger - but you do not need to recreate the manifest file for - subsequent additional segments. - - - Upload Manifest - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Length: 0 - X-Object-Meta-PIN: 1234 - X-Object-Manifest: container/object/segments - - - [...] - - - The response's Content-Type for a &GET; or - &HEAD; on the manifest will be the same as the - Content-Type set during the PUT request that created the - manifest. You can easily change the Content-Type by - reissuing the &PUT; request. -
-
- Chunked Transfer Encoding - Users can upload data without needing to know in advance - the amount of data to be uploaded. Users can do this by - specifying an HTTP header of Transfer-Encoding: - chunked and not using a Content-Length - header. A good use of this feature would be doing a DB dump, - piping the output through gzip, then piping the data - directly into OpenStack Object Storage without having to - buffer the data to disk to compute the file size. If users - attempt to upload more than 5GB with this method, the server - will close the TCP/IP connection after 5GB and purge the - customer data from the system. Users must take - responsibility for ensuring the data they transfer will be - less than 5GB or for splitting it into 5GB chunks, each in - its own storage object. If you have files that are larger - than 5GB and still want to use Object Storage, you can - segment them prior to upload, upload them to the same - container, and then use a manifest file to allow downloading - of a concatenated object containing all the segmented - objects, concatenated as a single object. - - Upload Unspecified Quantity of Content - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Transfer-Encoding: chunked - X-Object-Meta-PIN: 1234 - - - 19 - A bunch of data broken up - D - into chunks. - 0 - - -
-
-
- Assigning CORS Headers to Requests - CORS is a specification that stands for Cross-Origin Resource Sharing. It defines - how browsers and servers communicate across origins using HTTP headers, such as those - assigned by Cloud Files API requests. These headers are supported with the Cloud Files - API. You can read more about the definition of the Access-Control- response headers and - Origin response header at www.w3.org/TR/access-control/. - - Access-Control-Allow-Credentials - - - Access-Control-Allow-Methods - - - Access-Control-Allow-Origin - - - Access-Control-Expose-Headers - - - Access-Control-Max-Age - - - Access-Control-Request-Headers - - - Access-Control-Request-Method - - - Origin - - - These headers can be assigned to objects only. - - Assign CORS Header - In the example, the origin header is assigned that indicates where the file came - from. This allows you to provide security that requests to your Cloud Files repository - are indeed from the correct origination: - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Origin: http://storage.clouddrive.com - - -
-
- Enabling File Compression with the Content-Encoding Header - The Content-Encoding header allows a file to be compressed without losing the - identity of the underlying media type of the file, for example, a video. - - Content-Encoding Header Example - In the example, the content-encoding header is assigned with an attachment type - that indicates how the file should be downloaded: - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Type: video/mp4 - Content-Encoding: gzip - - -
-
- Enabling Browser Bypass with the Content-Disposition Header - When an object is assigned the Content-Disposition header you can override a - browser's default behavior for a file so that the downloader saves the file rather than - displaying it using default browser settings. - - Content-Disposition Header Example - In the example, the content-encoding header is assigned with an attachment type - that indicates how the file should be downloaded. - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Type: image/tiff - Content-Disposition: attachment; filename=platmap.tif - - -
-
- Expiring Objects with the X-Delete-After and X-Delete-At Headers - When an object is assigned either an X-Delete-After - or X-Delete-At header when doing a &PUT; or &POST; on the - object, it is scheduled for deletion. This feature is - helpful for objects you do not want to permanently store, - such as log files, recurring full backups of a dataset, or - documents or images you know will be outdated at a future - 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 and calculates the amount of time from now that - you want the object to be deleted. The proxy server that - receives the request converts this header into an - X-Delete-At header and calculates the deletion time using - its current time plus the value given in seconds. - For existing objects that you want to assign - expiration headers to, use the &POST; operation. - - Delete At Example - In the example, the X-Delete-At header is assigned with a Unix Epoch - timestamp in integer form for Mon, 11 Jun 2012 15:38:25 GMT. - Use http://www.epochconverter.com/ - for example timestamps and a batch converter. - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Type: image/jpeg - X-Delete-At: 1339429105 - - - - Delete After Example - - - In this example, the X-Delete-After header is assigned a value in seconds, - equivalent to 10 days. After this time, the object shall expire. - - - PUT /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.clouddrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - Content-Type: image/jpeg - X-Delete-After: 864000 - - -
- -
- Object Versioning - Object Versioning allows you to store multiple versions - of your content to recover from unintended overwrites. It - provides an easy method to implement version control which can - be used on any type of content. It is strongly recommended - that you put non-current objects in a container apart from - where the current versions exist. Once you enable Object - Versioning on a container (such as a "current version" - container), PUTs to existing objects in that container copy the - prior object to a separate "non-current version" container. - Each of the non-current versions of an object has a time stamp - appended to it, so you know when it was created. - To enable Object Versioning, your cloud provider has - to set allow_versions to TRUE in - their container config. Then, create a container where your - non-current versions will be written. Next, set the metadata - X-Versions-Location header on the container - that holds the current versions of your objects. Set the - metadata header to point to the new non-current version - container you created. This is where your non-current versions - will be stored. Once this is done, each object in your - current-version container will have Object Versioning enabled; - changes to the objects automatically create non-current - versions in the separate container. - - Nothing is written to the non-current version container when you initially - &PUT; an object into the current-version container. Only when you make - edits to the objects via &PUT; will you create non-current versions. These non-current - versions are labeled according to the schema below. - - - Naming Schema: Non-current versions are - assigned the name - <length><object_name>/<timestamp>, where - length is the 3-character zero-padded hexadecimal character - length of the <object_name> and <timestamp> is - when the it was initially created as a current version. - - Any return status in the 2xx range, such as 202 (Accepted), notes success. Status codes - in the 4xx or 5xx range note failure. You should retry your request if you receive an error. - Please note, however, that if you have specified a container that does not exist as your - non-current version container, a status of 412 (Precondition Failed) returns when you edit - the versioned object. If you receive this error, check that the container exists. - - - A &GET; to a versioned object returns the current version of the object without - having to do any request redirects or metadata lookups. - - - A &POST; to a versioned object only updates the object's metadata; it does - not create a new version of the object. In other words, new versions are only - created when the content of the object changes. - - - A &DELETE; to a versioned object removes the current version of the - object and replaces it with the next-most current version, moving it - from the non-current container to the current. - This next-most current version carries with it any metadata last set on it. - If want to completely remove an object and you have five total versions of it, - you must &DELETE; it five times. - - - Note: A large-object manifest file cannot be versioned, but it may point to - versioned segments. - - - To turn off Object Versioning on your current version container, remove its - X-Versions-Location metadata by sending an empty key value. - - - Object Versioning with cURL - Make sure a version-storing container exists, creating - it if necessary (this example names it "versions"). Then - create a container with the X-Versions-Location - header. In this example, this container is named "current". - You can also add the X-Versions-Location header - to an existing container. In this example, the name of the - container is “versions”; the location for the current - version is the container "current". - Create a container named versions. - curl -i -XPUT -H "X-Auth-Token: <token>" http://<storage_url>/versions - Create a container named current with the - X-Versions-Location header that references "versions". - - curl -i -XPUT -H "X-Auth-Token: <token>" \ - -H "X-Versions-Location: versions" http://<storage_url>/current - - Create an object (the first version): - - curl -i -XPUT --data-binary 1 -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - - Now create a new version of that object: - - curl -i -XPUT --data-binary 2 -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - - See a listing of the older versions of the object: - - curl -i -H "X-Auth-Token: <token>" \ - http://<storage_url>/versions?prefix=008myobject/ - - Now delete the current version of the object and see - that the older version is gone: - - curl -i -XDELETE -H "X-Auth-Token: <token>" \ - http://<storage_url>/current/myobject - curl -i -H "X-Auth-Token: <token>" \ - http://<storage_url>/versions?prefix=008myobject/ - - -
- - - - -
- Copy Object - Suppose you upload a file with the wrong object name or content type, or you - needed to move some objects to another container. Without a server-side copy feature, - you would need to repeat uploading the same content and then delete the existing - object. With server-side object copy, you can save the step of re-uploading the - content and thus also save the associated bandwidth charges, if any were to apply. - There are two ways to copy an existing object to another object in OpenStack Object Storage. - One way is to do a &PUT; to the new object (the target) location, but add the - “X-Copy-From” header to designate the source of the data. The header value should be - the container and object name of the source object in the form of “/container/object”. - Also, the X-Copy-From &PUT; requests require a Content-Length header, even if it is zero - (0). - PUT /<api version>/<account>/<container>/<destobject> HTTP/1.1 - Host: <storage URL> - X-Auth-Token: <some-auth-token> - X-Copy-From: /<container>/<sourceobject> - Content-Length: 0 - The second way to do an object copy is similar. Do a © to the existing object, - and include the “Destination” header to specify the target of the copy. The header - value is the container and new object name in the form of “/container/object”. - - COPY /<api version>/<account>/<container>/<sourceobject> HTTP/1.1 - Host: <storage URL> - X-Auth-Token: <some-auth-token> - Destination: /<container>/<destobject> - With both of these methods, the destination container must exist before - attempting the copy. - - If you wanted to move the object rather than copy it, you need to send a &DELETE; request to - the old object. A move is simply - a © + &DELETE;. All metadata is preserved during the object copy. Note that - you can set metadata on the request to copy the object (either the &PUT; or the ©) - and the metadata will overwrite any conflicting keys on the target (new) object. One - interesting use case is to copy an object to itself and set the content type to a new - value. This is the only way to change the content type of an existing object. - -
-
- Delete Object - &DELETE; operations on an object are used to permanently remove an - object from the storage system (metadata and data). - Deleting an object is processed immediately at the time of the request. Any - subsequent &GET;, &HEAD;, &POST;, or - &DELETE; operations will return a 404 (Not Found) error. - - Objects with the X-Delete-At or X-Delete-After header - assigned are deleted within one day of the expiration time - and the object is not served immediately after the - expiration time. Refer to Expiring Objects for more details. - - - Object Delete Request - - DELETE /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - No response body is returned. A status code of 204 (No Content) indicates success; - status code 404 (Not Found) is returned when the object does not exist. - - Object Delete Response - - HTTP/1.1 204 No Content - Date: Thu, 07 Jun 2010 20:59:39 GMT - Server: Apache - Content-Type: text/plain; charset=UTF-8 - - -
-
- Retrieve Object Metadata - &HEAD; operations on an object are used to retrieve object metadata and - other standard HTTP headers. - The only required header to be sent in the request is the authorization - token. - - Object Metadata Request - - HEAD /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - No response body is returned. Metadata is returned as HTTP headers. A status code of - 200 (OK) indicates success; status 404 (Not Found) is returned when the object does not - exist. - - - You may note that the &HEAD; return code for the object is different from that of the - container. &HEAD; requests do not return a message body in the response, so anything in - the 2xx response code range notes success. When a &HEAD; query is run against the - container, it queries the container databases, and it does not retrieve the content - of them, thus the 204 (No Content) return code. However, when a &HEAD; query is run - against the object, it returns an "OK" response because it can view the content. - In other words, the object &HEAD; query has a container length, but the container &HEAD; - query has zero content length. - - - Object Metadata Response - - HTTP/1.1 200 OK - Date: Thu, 07 Jun 2010 20:59:39 GMT - Server: Apache - Last-Modified: Fri, 12 Jun 2010 13:40:18 GMT - ETag: 8a964ee2a5e88be344f36c22562a6486 - Content-Length: 512000 - Content-Type: text/plain; charset=UTF-8 - X-Object-Meta-Meat: Bacon - X-Object-Meta-Fruit: Bacon - X-Object-Meta-Veggie: Bacon - X-Object-Meta-Dairy: Bacon - - -
-
- Update Object Metadata - &POST; operations against an object name are used to - set and overwrite arbitrary key/value metadata or to assign - headers not already assigned such as - X-Delete-At or X-Delete-After - for expiring objects. You cannot use the &POST; operation to - change any of the object's other headers such as - Content-Type, ETag, etc. It is - not used to upload storage objects (see &PUT;). Also refer - to copying an - object when you need to update metadata or other - headers such as Content-Type or CORS headers. - - Key names must be prefixed with X-Object-Meta-. A &POST; - request will delete all existing metadata added with a previous - &PUT;/&POST;. - - Update Object Metadata Request - - POST /<api version>/<account>/<container>/<object> HTTP/1.1 - Host: storage.swiftdrive.com - X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - X-Object-Meta-Fruit: Apple - X-Object-Meta-Veggie: Carrot - - - No response body is returned. A status code of 202 (Accepted) indicates success; - status 404 (Not Found) is returned if the requested object does not exist. - - Update Object Metadata Response - - HTTP/1.1 202 Accepted - Date: Thu, 07 Jun 2010 20:59:39 GMT - Server: Apache - Content-Length: 0 - Content-Type: text/plain; charset=UTF-8 - - -
-
- + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="ch_object-storage-dev-api-storage"> + API Operations for Storage Services + Use the ReST API to interact with the storage component of + OpenStack Object Storage. All requests are directed to the host + and URL described in the X-Storage-Url HTTP header + obtained during successful authentication. + Review the following requirements for using storage + services: + + + Container names cannot exceed 256 bytes and cannot contain + a '/' character. + + + Object names cannot exceed 1024 bytes and have no + character restrictions. + + + Object and container names must be URL-encoded and UTF-8 + encoded. + + + The + following sections describe the actions that you can perform in + the storage system. + + describes the + actions that you can perform at the account level of the + storage system. + + + describes + the actions that you can perform on containers. + + + + describes how to use your swift account to create a static + website. + + + describes the + actions that you can perform on objects. + + + + + + + diff --git a/openstack-object-storage-dev/src/docbkx/object-api-storage_account_svc.xml b/openstack-object-storage-dev/src/docbkx/object-api-storage_account_svc.xml new file mode 100644 index 0000000..07fbb6c --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/object-api-storage_account_svc.xml @@ -0,0 +1,305 @@ + + + + + + + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> + + + + + +'> + + + + + +'> +]> +
+ Storage Account Services + Perform the following operations at the account level of the + URL: + + + + Verb + URI + Description + + + + + &GET; + /account + Lists containers. + + + &HEAD; + /account + Gets account metadata. + + + &POST; + /account + Creates or updates account metadata. + + + &POST; + /account + Deletes account metadata. + + + + + For example, the URL for the requests end with the OpenStack + Object Storage account string, as follows: + + Storage Account Services HTTP Request + + +
+ List Containers + &GET; operations against the X-Storage-Url + for an account are performed to retrieve a list of + existing storage containers ordered by name. The sort + order for the name is based on a binary comparison, a single built-in collating + sequence that compares string data using SQLite's memcmp() + function, regardless of text encoding. The following list + describes the optional query parameters that are supported + with this request. + + Query Parameters + + limit + + For an integer value + n + , limits the number of + results to + n + values. + + + + marker + + Given a string value + x + , return container names + greater in value than the specified + marker. + + + + end_marker + + Given a string value + x + , return container names less + in value than the specified marker. + + + + format + + Specify either json or + xml to return the respective + serialized response. + + + + At this time, a prefix query parameter is + not supported at the account level. + + List Containers HTTP Request + + + A list of containers is returned in the response body, + one container per line. A 204 (No Content) HTTP return + code will be passed back if the account has no + containers. + + List Containers HTTP Response + + +
+ Serialized List Output + If a format=xml or + format=json argument is appended to + the storage account URL, the service serves extended + container information serialized in the chosen format. + The sample responses are formatted for readability. + The following HTTP request asks for a JSON response, + so the response returns an HTTP header and a JSON + response. + + Get Containers Details HTTP and JSON + Request + + + + Get Containers Details HTTP and JSON + Response + + + + The following HTTP request asks for an XML response, + so the response returns an HTTP header and an XML + response. + + Containers Details HTTP and XML Request + + + + Containers Details HTTP and XML + Response + + + +
+
+ Controlling a Large List of Containers + The system returns a maximum of 10,000 container + names per request. To retrieve subsequent container + names, another request must be made with the 'marker' + parameter. The marker indicates where the last list + left off; the system returns container names greater + than this marker, up to 10,000 again. Note that the + ‘marker’ value should be URL-encoded prior to sending + the HTTP request. + If 10,000 is larger than desired, use the 'limit' + parameter. + If the number of container names returned equals the + limit given (or 10,000 if no limit is given), you may + assume there are more container names. + + List Large Number of Containers + For example, let's use a listing of five + container names: + apples +bananas +kiwis +oranges +pears + We'll use a limit of two to show how things + work: + + apples +bananas + Because we received two items back, we can assume + there are more container names to list, so we make + another request with a marker of the last item + returned: + + kiwis +oranges + Again, two items are returned; there might be + more: + + pears + With this one-item response we received less + than the limit number of container names, + indicating that this is the end of the + list. + By using end_marker we can limit + the result set to container names less than the + given value. + + apples +bananas +kiwis + +
+
+
+ Get Account Metadata + &HEAD; operations against an account are performed to + retrieve the number of containers and the total bytes + stored in OpenStack Object Storage for the account. This + information is returned in two custom headers, + X-Account-Container-Count and + X-Account-Bytes-Used. Since the storage + system is designed to store large amounts of data, care + should be taken when representing the total bytes response + as an integer; when possible, convert it to a 64-bit + unsigned integer if your platform supports that primitive + type. + + Get Account Metadata HTTP Request + + + The HTTP return code will be 204 (No Content) if the + request succeeds. A 401 (Unauthorized) will be returned + for an invalid account or access key. + + Get Account Metadata HTTP Response + + +
+
+ Create or Update Account Metadata + You can associate custom metadata headers with the + account level URI. These headers must take the format + X-Account-Meta-*. + To create or update an account metadata header use the + &POST; query. Subsequent requests for the same key/value + pair overwrite the previous value. + + Update Account Metadata HTTP Request + + + No response body is returned. A status code of 204 (No + Content) indicates success. + + Update Account Metadata HTTP Response + + + To confirm your metadata changes, perform a &HEAD; + request on the account. Do not send the metadata in your + &HEAD; request. + + View Account Metadata HTTP Request + + + + View Account Metadata HTTP Response + + +
+
+ Delete Account Metadata + To delete a metadata header send an empty value for that + particular header, such as + X-Account-Meta-Book. + If the tool you're using to communicate with Swift + doesn't support sending empty headers (such as older + versions of cURL) send the header + "X-Remove-Account-Meta-name: + arbitrary value", such as + X-Remove-Account-Meta-Book: x. The + value is ignored. + + Delete Account Metadata HTTP Request + + No response body is returned. A status code of 204 + (No Content) indicates success. + +
+
diff --git a/openstack-object-storage-dev/src/docbkx/os-objectstorage-devguide.xml b/openstack-object-storage-dev/src/docbkx/os-objectstorage-devguide.xml index 0832bca..6a85ff8 100644 --- a/openstack-object-storage-dev/src/docbkx/os-objectstorage-devguide.xml +++ b/openstack-object-storage-dev/src/docbkx/os-objectstorage-devguide.xml @@ -51,11 +51,13 @@ 2010 2011 2012 + 2013 OpenStack, LLC API v1 OpenStack Object Storage - 2012-09-04 + + 2013-02-22 Copyright details are filled in by the template. @@ -68,6 +70,17 @@ (API). + + 2013-02-2 + + + + Moved code samples into separate files for content sharing. + + + + + 2012-09-12 @@ -173,4 +186,6 @@ + + diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-delete-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/account-delete-metadata-req.txt new file mode 100644 index 0000000..a3f6309 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-delete-metadata-req.txt @@ -0,0 +1,4 @@ +POST // HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Remove-Account-Meta-Book: x \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-req.txt new file mode 100644 index 0000000..05cf1fb --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-req.txt @@ -0,0 +1,3 @@ +HEAD // HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-resp.txt new file mode 100644 index 0000000..2e45920 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-get-metadata-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 204 No Content +Date: Thu, 07 Jun 2010 18:57:07 GMT +Server: Apache +X-Account-Container-Count: 3 +X-Account-Bytes-Used: 323479 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-req.txt new file mode 100644 index 0000000..470a856 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-req.txt @@ -0,0 +1,5 @@ +POST // HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Account-Meta-Book: MobyDick +X-Account-Meta-Subject: Whaling \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-resp.txt new file mode 100644 index 0000000..e18ce4e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-update-metadata-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 204 No Content +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +Date: Sat, 09 Jun 2012 19:16:29 GMT \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-req.txt new file mode 100644 index 0000000..5b94dc4 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-req.txt @@ -0,0 +1,3 @@ +HEAD // HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-resp.txt new file mode 100644 index 0000000..d3b873b --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/account-view-metadata-resp.txt @@ -0,0 +1,10 @@ +HTTP/1.1 204 No Content +X-Account-Meta-Book: MobyDick +X-Account-Meta-Subject: Whaling +X-Account-Object-Count: 5 +X-Timestamp: 1323466696.21566 +X-Account-Container-Count: 5 +X-Account-Bytes-Used: 46988 +Accept-Ranges: bytes +Content-Length: 0 +Date: Sat, 09 Jun 2012 19:16:59 GMT \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/auth-req.txt b/openstack-object-storage-dev/src/docbkx/samples/auth-req.txt new file mode 100644 index 0000000..b263297 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/auth-req.txt @@ -0,0 +1,4 @@ +GET /v1.0 HTTP/1.1 +Host: auth.api.yourcloud.com +X-Auth-User: jdoe +X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/auth-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/auth-resp.txt new file mode 100644 index 0000000..f32e0f8 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/auth-resp.txt @@ -0,0 +1,7 @@ +HTTP/1.1 204 No Content +Date: Mon, 12 Nov 2010 15:32:21 GMT +Server: Apache +X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_34 +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-req.txt b/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-req.txt new file mode 100644 index 0000000..b65ecfc --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-req.txt @@ -0,0 +1,5 @@ + PUT //// HTTP/1.1 + Host: storage.swiftdrive.com + X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb + Transfer-Encoding: chunked + X-Object-Meta-PIN: 1234 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-resp.txt new file mode 100644 index 0000000..44d8631 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/chunked-transfer-encoding-resp.txt @@ -0,0 +1,5 @@ +19 +A bunch of data broken up +D +into chunks. +0 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-req.txt new file mode 100644 index 0000000..9fe5e73 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-req.txt @@ -0,0 +1,4 @@ +PUT /// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Container-Meta-InspectedBy: JackWolf \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-resp.txt new file mode 100644 index 0000000..41750aa --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-create-metadata-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 201 Created +Date: Thu, 07 Jun 2010 18:50:19 GMT +Server: Apache +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-create-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-create-req.txt new file mode 100644 index 0000000..45e4200 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-create-req.txt @@ -0,0 +1,3 @@ +PUT /// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-create-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-create-resp.txt new file mode 100644 index 0000000..5c77bc1 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-create-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 201 Created +Date: Thu, 07 Jun 2007 18:50:19 GMT +Server: Apache +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-delete-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-delete-metadata-req.txt new file mode 100644 index 0000000..cf2ebfa --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-delete-metadata-req.txt @@ -0,0 +1,4 @@ +POST /// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Remove-Container-Meta-Book: x \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-delete-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-delete-req.txt new file mode 100644 index 0000000..ec81221 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-delete-req.txt @@ -0,0 +1,3 @@ +DELETE /// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-delete-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-delete-resp.txt new file mode 100644 index 0000000..5e0444f --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-delete-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 204 No Content +Date: Thu, 07 Jun 2010 18:57:07 GMT +Server: Apache +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-json-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-json-resp.txt new file mode 100644 index 0000000..e860369 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-json-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Date: Tue, 25 Nov 2008 19:39:13 GMT +Server: Apache +Content-Type: application/json; charset=utf-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-xml-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-xml-resp.txt new file mode 100644 index 0000000..2f03f08 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-http-xml-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Date: Tue, 25 Nov 2008 19:42:35 GMT +Server: Apache +Content-Type: application/xml; charset=utf-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-json-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-json-req.txt new file mode 100644 index 0000000..71c3b61 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-json-req.txt @@ -0,0 +1,4 @@ +GET //?format=json HTTP/1.1 +Host: storage.swiftdrive.com +Content-Length: 0 +X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.json b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.json new file mode 100644 index 0000000..abca446 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.json @@ -0,0 +1,4 @@ +[ + {"name":"test_container_1", "count":2, "bytes":78}, + {"name":"test_container_2", "count":1, "bytes":17} +] \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.xml b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.xml new file mode 100644 index 0000000..86464d6 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-resp.xml @@ -0,0 +1,13 @@ + + + + test_container_1 + 2 + 78 + + + test_container_2 + 1 + 17 + + \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-details-xml-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-xml-req.txt new file mode 100644 index 0000000..62d329d --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-details-xml-req.txt @@ -0,0 +1,4 @@ +GET //?format=xml HTTP/1.1 +Host: storage.swiftdrive.com +Content-Length: 0 +X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-req.txt new file mode 100644 index 0000000..60440b1 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-req.txt @@ -0,0 +1,3 @@ +HEAD /// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-resp.txt new file mode 100644 index 0000000..670f15e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-get-metadata-resp.txt @@ -0,0 +1,6 @@ +HTTP/1.1 204 No Content +Date: Wed, 11 Jul 2010 19:37:41 GMT +Content-type: text/html +X-Container-Object-Count: 7 +X-Container-Bytes-Used: 413 +X-Container-Meta-InspectedBy: JackWolf \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-req.txt new file mode 100644 index 0000000..3ff6ffa --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-req.txt @@ -0,0 +1,5 @@ +POST //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Container-Meta-Book: MobyDick +X-Container-Meta-Subject: Whaling \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-resp.txt new file mode 100644 index 0000000..ba77bc7 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-update-metadata-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 204 No Content +Date: Thu, 07 Mar 2012 20:42:51 GMT +Server: Apache +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-req.txt new file mode 100644 index 0000000..f9875db --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-req.txt @@ -0,0 +1,3 @@ +HEAD //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-resp.txt new file mode 100644 index 0000000..b60c751 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/container-view-metadata-resp.txt @@ -0,0 +1,9 @@ +HTTP/1.1 204 No Content +X-Container-Object-Count: 0 +X-Trans-Id: tx028b40d228534c759f4d5fa69f8cf7fd +X-Container-Meta-Book: MobyDick +X-Container-Meta-Subject: Whaling +Accept-Ranges: bytes +Date: Mon, 12 Mar 2012 16:40:20 GMT +Content-Length: 0 +X-Container-Bytes-Used: 0 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/containers-list-req.txt b/openstack-object-storage-dev/src/docbkx/samples/containers-list-req.txt new file mode 100644 index 0000000..4cad48f --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/containers-list-req.txt @@ -0,0 +1,3 @@ +GET // HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/containers-list-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/containers-list-resp.txt new file mode 100644 index 0000000..3e52c57 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/containers-list-resp.txt @@ -0,0 +1,10 @@ +HTTP/1.1 200 Ok +Date: Thu, 07 Jun 2010 18:57:07 GMT +Server: Apache +Content-Type: text/plain; charset=UTF-8 +Content-Length: 32 + +images +movies +documents +backups \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/content-disposition-header-req.txt b/openstack-object-storage-dev/src/docbkx/samples/content-disposition-header-req.txt new file mode 100644 index 0000000..5dfe3af --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/content-disposition-header-req.txt @@ -0,0 +1,5 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Type: image/tiff +Content-Disposition: attachment; filename=platmap.tif \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/content-encoding-header-req.txt b/openstack-object-storage-dev/src/docbkx/samples/content-encoding-header-req.txt new file mode 100644 index 0000000..52be28b --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/content-encoding-header-req.txt @@ -0,0 +1,5 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Type: video/mp4 +Content-Encoding: gzip \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/error-page-set-req.txt b/openstack-object-storage-dev/src/docbkx/samples/error-page-set-req.txt new file mode 100644 index 0000000..b7f87bf --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/error-page-set-req.txt @@ -0,0 +1 @@ +swift post -m 'web-error:error.html' container \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/file-listings-css-set-req.txt b/openstack-object-storage-dev/src/docbkx/samples/file-listings-css-set-req.txt new file mode 100644 index 0000000..3ff03b4 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/file-listings-css-set-req.txt @@ -0,0 +1 @@ +swift post -m 'web-listings-css:listings.css' container \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-end-marker-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-end-marker-req.txt new file mode 100644 index 0000000..8e18ee5 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-end-marker-req.txt @@ -0,0 +1,3 @@ +GET /?end_marker=oranges +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-req.txt new file mode 100644 index 0000000..31a4da2 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter-req.txt @@ -0,0 +1,3 @@ +GET //?limit=2&marker=bananas +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter2-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter2-req.txt new file mode 100644 index 0000000..250ce0c --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-filter2-req.txt @@ -0,0 +1,3 @@ +GET //?limit=2&marker=oranges +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-container-list-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-req.txt new file mode 100644 index 0000000..968c404 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-container-list-req.txt @@ -0,0 +1,3 @@ +GET //?limit=2 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-next-segment-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-next-segment-req.txt new file mode 100644 index 0000000..9fbf703 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-next-segment-req.txt @@ -0,0 +1,6 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +ETag: 8a964ee2a5e88be344f36c22562a6486 +Content-Length: 1 +X-Object-Meta-PIN: 1234 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-segment-req.txt b/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-segment-req.txt new file mode 100644 index 0000000..9fbf703 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/large-object-upload-segment-req.txt @@ -0,0 +1,6 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +ETag: 8a964ee2a5e88be344f36c22562a6486 +Content-Length: 1 +X-Object-Meta-PIN: 1234 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-api-general-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-api-general-req.txt new file mode 100644 index 0000000..a4882a3 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-api-general-req.txt @@ -0,0 +1 @@ + /v1/ HTTP/1.1 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-assign-cors-header-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-assign-cors-header-req.txt new file mode 100644 index 0000000..fa86e67 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-assign-cors-header-req.txt @@ -0,0 +1,4 @@ +PUT //// HTTP/1.1 +Host: +X-Auth-Token: +X-Copy-From: // +Content-Length: 0 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-copy-2-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-copy-2-req.txt new file mode 100644 index 0000000..e65adc8 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-copy-2-req.txt @@ -0,0 +1,4 @@ +COPY //<account>// HTTP/1.1 +Host: +X-Auth-Token: +Destination: // \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-create-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-create-req.txt new file mode 100644 index 0000000..b136f3a --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-create-req.txt @@ -0,0 +1,6 @@ +PUT //// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +ETag: 8a964ee2a5e88be344f36c22562a6486 +Content-Length: 512000 +X-Object-Meta-PIN: 1234 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-create-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-create-resp.txt new file mode 100644 index 0000000..7e66e93 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-create-resp.txt @@ -0,0 +1,6 @@ +HTTP/1.1 201 Created +Date: Thu, 07 Jun 2010 18:57:07 GMT +Server: Apache +ETag: d9f5eb4bba4e2f2f046e54611bc8196b +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-delete-after-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-delete-after-req.txt new file mode 100644 index 0000000..640a83f --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-delete-after-req.txt @@ -0,0 +1,5 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Type: image/jpeg +X-Delete-After: 864000 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-delete-at-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-delete-at-req.txt new file mode 100644 index 0000000..5237d1a --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-delete-at-req.txt @@ -0,0 +1,5 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Type: image/jpeg +X-Delete-At: 1339429105 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-delete-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-delete-req.txt new file mode 100644 index 0000000..717716e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-delete-req.txt @@ -0,0 +1,3 @@ +DELETE //// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-delete-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-delete-resp.txt new file mode 100644 index 0000000..6872381 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-delete-resp.txt @@ -0,0 +1,4 @@ +HTTP/1.1 204 No Content +Date: Thu, 07 Jun 2010 20:59:39 GMT +Server: Apache +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-get-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-get-req.txt new file mode 100644 index 0000000..2bbfa37 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-get-req.txt @@ -0,0 +1,3 @@ +GET //// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-get-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-get-resp.txt new file mode 100644 index 0000000..7885633 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-get-resp.txt @@ -0,0 +1,7 @@ +HTTP/1.1 200 Ok +Date: Wed, 11 Jul 2010 19:37:41 GMT +Server: Apache +Last-Modified: Fri, 12 Jun 2010 13:40:18 GMT +ETag: b0dffe8254d152d8fd28f3c5e0404a10 +Content-type: text/html +Content-Length: 512000 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-list-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-list-req.txt new file mode 100644 index 0000000..6f0f731 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-list-req.txt @@ -0,0 +1,3 @@ +GET ///[?parm=value] HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-list-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-list-resp.txt new file mode 100644 index 0000000..5f71768 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-list-resp.txt @@ -0,0 +1,14 @@ +HTTP/1.1 200 Ok +Date: Thu, 07 Jun 2010 18:50:19 GMT +Server: Apache +Content-Type: text/plain; charset=UTF-8 +Content-Length: 171 + + +kate_beckinsale.jpg +How To Win Friends And Influence People.pdf +moms_birthday.jpg +poodle_strut.mov +Disturbed - Down With The Sickness.mp3 +army_of_darkness.avi +the_mad.avi \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-metadata-req.txt new file mode 100644 index 0000000..42e7317 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-metadata-req.txt @@ -0,0 +1,3 @@ +HEAD /<api version>/<account>/<container>/<object> HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-metadata-resp.txt new file mode 100644 index 0000000..8549208 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-metadata-resp.txt @@ -0,0 +1,11 @@ +HTTP/1.1 200 OK +Date: Thu, 07 Jun 2010 20:59:39 GMT +Server: Apache +Last-Modified: Fri, 12 Jun 2010 13:40:18 GMT +ETag: 8a964ee2a5e88be344f36c22562a6486 +Content-Length: 512000 +Content-Type: text/plain; charset=UTF-8 +X-Object-Meta-Meat: Bacon +X-Object-Meta-Fruit: Bacon +X-Object-Meta-Veggie: Bacon +X-Object-Meta-Dairy: Bacon \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-req.txt b/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-req.txt new file mode 100644 index 0000000..3868801 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-req.txt @@ -0,0 +1,5 @@ +POST //// HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Object-Meta-Fruit: Apple +X-Object-Meta-Veggie: Carrot \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-resp.txt new file mode 100644 index 0000000..0d72e8f --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/object-update-metadata-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 202 Accepted +Date: Thu, 07 Jun 2010 20:59:39 GMT +Server: Apache +Content-Length: 0 +Content-Type: text/plain; charset=UTF-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-req.txt new file mode 100644 index 0000000..65c3265 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-req.txt @@ -0,0 +1,4 @@ +GET ///?format=json HTTP/1.1 +Host: storage.swiftdrive.com +Content-Length: 0 +X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-resp.txt new file mode 100644 index 0000000..efcd7e7 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-json-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 200 OK +Date: Tue, 25 Nov 2008 19:39:13 GMT +Server: Apache +Content-Length: 387 +Content-Type: application/json; charset=utf-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-req.txt new file mode 100644 index 0000000..13f009e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-req.txt @@ -0,0 +1,3 @@ +GET ///?format=xml HTTP/1.1 +Host: storage.swiftdrive.com +X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-resp.txt new file mode 100644 index 0000000..b55ac6d --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-http-xml-resp.txt @@ -0,0 +1,5 @@ +HTTP/1.1 200 OK +Date: Tue, 25 Nov 2008 19:42:35 GMT +Server: Apache +Content-Length: 643 +Content-Type: application/xml; charset=utf-8 \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.json b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.json new file mode 100644 index 0000000..526a7f5 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.json @@ -0,0 +1,12 @@ +[ + {"name":"test_obj_1", + "hash":"4281c348eaf83e70ddce0e07221c3d28", + "bytes":14, + "content_type":"application\/octet-stream", + "last_modified":"2009-02-03T05:26:32.612278"}, + {"name":"test_obj_2", + "hash":"b039efe731ad111bc1b0ef221c3849d0", + "bytes":64, + "content_type":"application\/octet-stream", + "last_modified":"2009-02-03T05:26:32.612278"}, +] \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.xml b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.xml new file mode 100644 index 0000000..a6fd5e8 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-get-details-resp.xml @@ -0,0 +1,17 @@ + + + + test_object_1 + 4281c348eaf83e70ddce0e07221c3d28 + 14 + application/octet-stream + 2009-02-03T05:26:32.612278 + + + test_object_2 + b039efe731ad111bc1b0ef221c3849d0 + 64 + application/octet-stream + 2009-02-03T05:26:32.612278 + + \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-list-end-marker-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-list-end-marker-req.txt new file mode 100644 index 0000000..57a3847 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-list-end-marker-req.txt @@ -0,0 +1,8 @@ +GET //?end_marker=jonagold +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb + + +gala +grannysmith +honeycrisp \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker-req.txt new file mode 100644 index 0000000..84026e4 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker-req.txt @@ -0,0 +1,7 @@ +GET ///?limit=2&marker=grannysmith +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb + + +honeycrisp +jonagold \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker2-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker2-req.txt new file mode 100644 index 0000000..fea77a9 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-list-marker2-req.txt @@ -0,0 +1,6 @@ +GET ///?limit=2&marker=jonagold +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb + + +reddelicious \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/objects-list-req.txt b/openstack-object-storage-dev/src/docbkx/samples/objects-list-req.txt new file mode 100644 index 0000000..8bd6eca --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/objects-list-req.txt @@ -0,0 +1,7 @@ +GET ///?limit=2 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb + + +gala +grannysmith \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/proxy-server-excerpt.conf b/openstack-object-storage-dev/src/docbkx/samples/proxy-server-excerpt.conf new file mode 100644 index 0000000..30c0d8a --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/proxy-server-excerpt.conf @@ -0,0 +1,20 @@ +[DEFAULT] +... + +[pipeline:main] +pipeline = healthcheck cache tempauth staticweb proxy-server + +... + +[filter:staticweb] +use = egg:swift#staticweb +# Seconds to cache container x-container-meta-web-* header values. +# cache_timeout = 300 +# You can override the default log routing for this filter here: +# set log_name = staticweb +# set log_facility = LOG_LOCAL0 +# set log_level = INFO +# set access_log_name = staticweb +# set access_log_facility = LOG_LOCAL0 +# set access_log_level = INFO +# set log_headers = False \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-req.txt b/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-req.txt new file mode 100644 index 0000000..c5c4744 --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-req.txt @@ -0,0 +1,6 @@ +PUT //// HTTP/1.1 +Host: storage.clouddrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Content-Length: 0 +X-Object-Meta-PIN: 1234 +X-Object-Manifest: container/object/segments \ No newline at end of file diff --git a/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-resp.txt b/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-resp.txt new file mode 100644 index 0000000..c92b79e --- /dev/null +++ b/openstack-object-storage-dev/src/docbkx/samples/upload-manifest-resp.txt @@ -0,0 +1 @@ +[...] \ No newline at end of file