5 An object is a container for storing data and metadata. A container may
6 have many objects, but the object names must be unique. This API enables a
7 client to create an object, set access controls and metadata, retrieve an
8 object's data and metadata, and delete an object. Since this API makes requests
9 related to information in a particular user's account, all requests in this API
10 must be authenticated unless the container or object's access control is
11 deliberately made publicly accessible (i.e., allows anonymous requests).
14 Create/Update an Object
15 =======================
17 To create a new object, make a ``PUT`` request with the API version, account,
18 container name and the name of the new object. You must have write permission
19 on the container to create or update an object. The object name must be
20 unique within the container. The ``PUT`` request is not idempotent, so if you
21 do not use a unique name, the request will update the object. However, you may
22 use pseudo-hierarchical syntax in your object name to distinguish it from
23 another object of the same name if it is under a different pseudo-hierarchical
24 directory. You may include access control headers and metadata headers in the
33 PUT /{api version}/{account}/{container}/{object} HTTP/1.1
35 X-Auth-Token: {auth-token}
43 :Description: An MD5 hash of the object's contents. Recommended.
50 :Description: The type of content the object contains.
57 :Description: Indicates whether the object is part of a larger aggregate object.
59 :Valid Values: ``chunked``
66 Copying an object allows you to make a server-side copy of an object, so that
67 you don't have to download it and upload it under another container/name.
68 To copy the contents of one object to another object, you may make either a
69 ``PUT`` request or a ``COPY`` request with the API version, account, and the
70 container name. For a ``PUT`` request, use the destination container and object
71 name in the request, and the source container and object in the request header.
72 For a ``Copy`` request, use the source container and object in the request, and
73 the destination container and object in the request header. You must have write
74 permission on the container to copy an object. The destination object name must be
75 unique within the container. The request is not idempotent, so if you do not use
76 a unique name, the request will update the destination object. However, you may
77 use pseudo-hierarchical syntax in your object name to distinguish the destination
78 object from the source object of the same name if it is under a different
79 pseudo-hierarchical directory. You may include access control headers and metadata
80 headers in the request.
87 PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1
88 X-Copy-From: {source-container}/{source-object}
90 X-Auth-Token: {auth-token}
97 COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1
98 Destination: {dest-container}/{dest-object}
105 :Description: Used with a ``PUT`` request to define the source container/object path.
107 :Required: Yes, if using ``PUT``
112 :Description: Used with a ``COPY`` request to define the destination container/object path.
114 :Required: Yes, if using ``COPY``
117 ``If-Modified-Since``
119 :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
124 ``If-Unmodified-Since``
126 :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
132 :Description: Copies only if the ETag in the request matches the source object's ETag.
137 ``Copy-If-None-Match``
139 :Description: Copies only if the ETag in the request does not match the source object's ETag.
147 To delete an object, make a ``DELETE`` request with the API version, account,
148 container and object name. You must have write permissions on the container to delete
149 an object within it. Once you have successfully deleted the object, you will be able to
150 reuse the object name.
157 DELETE /{api version}/{account}/{container}/{object} HTTP/1.1
159 X-Auth-Token: {auth-token}
165 To retrieve an object, make a ``GET`` request with the API version, account,
166 container and object name. You must have read permissions on the container to
167 retrieve an object within it.
174 GET /{api version}/{account}/{container}/{object} HTTP/1.1
176 X-Auth-Token: {auth-token}
185 :Description: To retrieve a subset of an object's contents, you may specify a byte range.
190 ``If-Modified-Since``
192 :Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
197 ``If-Unmodified-Since``
199 :Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
205 :Description: Copies only if the ETag in the request matches the source object's ETag.
210 ``Copy-If-None-Match``
212 :Description: Copies only if the ETag in the request does not match the source object's ETag.
223 :Description: The range of the subset of object contents. Returned only if the range header field was specified in the request
229 To retrieve an object's metadata, make a ``HEAD`` request with the API version,
230 account, container and object name. You must have read permissions on the
231 container to retrieve metadata from an object within the container. This request
232 returns the same header information as the request for the object itself, but
233 it does not return the object's data.
240 HEAD /{api version}/{account}/{container}/{object} HTTP/1.1
242 X-Auth-Token: {auth-token}
246 Add/Update Object Metadata
247 ==========================
249 To add metadata to an object, make a ``POST`` request with the API version,
250 account, container and object name. You must have write permissions on the
251 parent container to add or update metadata.
259 POST /{api version}/{account}/{container}/{object} HTTP/1.1
261 X-Auth-Token: {auth-token}
266 ``X-Object-Meta-{key}``
268 :Description: A user-defined meta data key that takes an arbitrary string value.