1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
===================
Object Operations
===================
An object is a container for storing data and metadata. A container may
have many objects, but the object names must be unique. This API enables a
client to create an object, set access controls and metadata, retrieve an
object's data and metadata, and delete an object. Since this API makes requests
related to information in a particular user's account, all requests in this API
must be authenticated unless the container or object's access control is
deliberately made publicly accessible (i.e., allows anonymous requests).
Create/Update an Object
=======================
To create a new object, make a ``PUT`` request with the API version, account,
container name and the name of the new object. You must have write permission
on the container to create or update an object. The object name must be
unique within the container. The ``PUT`` request is not idempotent, so if you
do not use a unique name, the request will update the object. However, you may
use pseudo-hierarchical syntax in your object name to distinguish it from
another object of the same name if it is under a different pseudo-hierarchical
directory. You may include access control headers and metadata headers in the
request.
Syntax
~~~~~~
::
PUT /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
Request Headers
~~~~~~~~~~~~~~~
``ETag``
:Description: An MD5 hash of the object's contents. Recommended.
:Type: String
:Required: No
``Content-Type``
:Description: The type of content the object contains.
:Type: String
:Required: No
``Transfer-Encoding``
:Description: Indicates whether the object is part of a larger aggregate object.
:Type: String
:Valid Values: ``chunked``
:Required: No
Copy an Object
==============
Copying an object allows you to make a server-side copy of an object, so that
you don't have to download it and upload it under another container/name.
To copy the contents of one object to another object, you may make either a
``PUT`` request or a ``COPY`` request with the API version, account, and the
container name. For a ``PUT`` request, use the destination container and object
name in the request, and the source container and object in the request header.
For a ``Copy`` request, use the source container and object in the request, and
the destination container and object in the request header. You must have write
permission on the container to copy an object. The destination object name must be
unique within the container. The request is not idempotent, so if you do not use
a unique name, the request will update the destination object. However, you may
use pseudo-hierarchical syntax in your object name to distinguish the destination
object from the source object of the same name if it is under a different
pseudo-hierarchical directory. You may include access control headers and metadata
headers in the request.
Syntax
~~~~~~
::
PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1
X-Copy-From: {source-container}/{source-object}
Host: {fqdn}
X-Auth-Token: {auth-token}
or alternatively:
::
COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1
Destination: {dest-container}/{dest-object}
Request Headers
~~~~~~~~~~~~~~~
``X-Copy-From``
:Description: Used with a ``PUT`` request to define the source container/object path.
:Type: String
:Required: Yes, if using ``PUT``
``Destination``
:Description: Used with a ``COPY`` request to define the destination container/object path.
:Type: String
:Required: Yes, if using ``COPY``
``If-Modified-Since``
:Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
:Type: Date
:Required: No
``If-Unmodified-Since``
:Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
:Type: Date
:Required: No
``Copy-If-Match``
:Description: Copies only if the ETag in the request matches the source object's ETag.
:Type: ETag.
:Required: No
``Copy-If-None-Match``
:Description: Copies only if the ETag in the request does not match the source object's ETag.
:Type: ETag.
:Required: No
Delete an Object
================
To delete an object, make a ``DELETE`` request with the API version, account,
container and object name. You must have write permissions on the container to delete
an object within it. Once you have successfully deleted the object, you will be able to
reuse the object name.
Syntax
~~~~~~
::
DELETE /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
Get an Object
=============
To retrieve an object, make a ``GET`` request with the API version, account,
container and object name. You must have read permissions on the container to
retrieve an object within it.
Syntax
~~~~~~
::
GET /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
Request Headers
~~~~~~~~~~~~~~~
``range``
:Description: To retrieve a subset of an object's contents, you may specify a byte range.
:Type: Date
:Required: No
``If-Modified-Since``
:Description: Only copies if modified since the date/time of the source object's ``last_modified`` attribute.
:Type: Date
:Required: No
``If-Unmodified-Since``
:Description: Only copies if not modified since the date/time of the source object's ``last_modified`` attribute.
:Type: Date
:Required: No
``Copy-If-Match``
:Description: Copies only if the ETag in the request matches the source object's ETag.
:Type: ETag.
:Required: No
``Copy-If-None-Match``
:Description: Copies only if the ETag in the request does not match the source object's ETag.
:Type: ETag.
:Required: No
Response Headers
~~~~~~~~~~~~~~~~
``Content-Range``
:Description: The range of the subset of object contents. Returned only if the range header field was specified in the request
Get Object Metadata
===================
To retrieve an object's metadata, make a ``HEAD`` request with the API version,
account, container and object name. You must have read permissions on the
container to retrieve metadata from an object within the container. This request
returns the same header information as the request for the object itself, but
it does not return the object's data.
Syntax
~~~~~~
::
HEAD /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
Add/Update Object Metadata
==========================
To add metadata to an object, make a ``POST`` request with the API version,
account, container and object name. You must have write permissions on the
parent container to add or update metadata.
Syntax
~~~~~~
::
POST /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}
Request Headers
~~~~~~~~~~~~~~~
``X-Object-Meta-{key}``
:Description: A user-defined meta data key that takes an arbitrary string value.
:Type: String
:Required: No
|
