root / docs / source / devguide.rst @ 75453cf2
History | View | Annotate | Download (57.9 kB)
1 | f2d7b5ab | Antony Chazapis | Pithos v2 Developer Guide |
---|---|---|---|
2 | f2d7b5ab | Antony Chazapis | ========================= |
3 | f2d7b5ab | Antony Chazapis | |
4 | f2d7b5ab | Antony Chazapis | Introduction |
5 | f2d7b5ab | Antony Chazapis | ------------ |
6 | f2d7b5ab | Antony Chazapis | |
7 | f2d7b5ab | Antony Chazapis | Pithos is a storage service implemented by GRNET (http://www.grnet.gr). Data is stored as objects, organized in containers, belonging to an account. This hierarchy of storage layers has been inspired by the OpenStack Object Storage (OOS) API and similar CloudFiles API by Rackspace. The Pithos API follows the OOS API as closely as possible. One of the design requirements has been to be able to use Pithos with clients built for the OOS, without changes. |
8 | f2d7b5ab | Antony Chazapis | |
9 | 3ab38c43 | Antony Chazapis | However, to be able to take full advantage of the Pithos infrastructure, client software should be aware of the extensions that differentiate Pithos from OOS. Pithos objects can be updated, or appended to. Pithos will store sharing permissions per object and enforce corresponding authorization policies. Automatic version management, allows taking account and container listings back in time, as well as reading previous instances of objects. |
10 | e9285524 | Antony Chazapis | |
11 | c9af0703 | Antony Chazapis | The storage backend of Pithos is block oriented, permitting efficient, deduplicated data placement. The block structure of objects is exposed at the API layer, in order to encourage external software to implement advanced data management operations. |
12 | e9285524 | Antony Chazapis | |
13 | f2d7b5ab | Antony Chazapis | This document's goals are: |
14 | f2d7b5ab | Antony Chazapis | |
15 | f2d7b5ab | Antony Chazapis | * Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls |
16 | f2d7b5ab | Antony Chazapis | * Specify metadata semantics and user interface guidelines for a common experience across client software implementations |
17 | f2d7b5ab | Antony Chazapis | |
18 | f2d7b5ab | Antony Chazapis | The present document is meant to be read alongside the OOS API documentation. Thus, it is suggested that the reader is familiar with associated technologies, the OOS API as well as the first version of the Pithos API. This document refers to the second version of Pithos. Information on the first version of the storage API can be found at http://code.google.com/p/gss. |
19 | f2d7b5ab | Antony Chazapis | |
20 | f2d7b5ab | Antony Chazapis | Whatever marked as to be determined (**TBD**), should not be considered by implementors. |
21 | f2d7b5ab | Antony Chazapis | |
22 | f2d7b5ab | Antony Chazapis | Document Revisions |
23 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^^^^^^^^^^ |
24 | f2d7b5ab | Antony Chazapis | |
25 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
26 | f2d7b5ab | Antony Chazapis | Revision Description |
27 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
28 | a8326bef | Antony Chazapis | 0.5 (July 22, 2011) Object update from another object's data. |
29 | 1495b972 | Antony Chazapis | \ Support object truncate. |
30 | 1d5c57d3 | Antony Chazapis | \ Create object using a standard HTML form. |
31 | 81f947fd | Antony Chazapis | \ Purge container/object history. |
32 | f6c97079 | Antony Chazapis | \ List other accounts that share objects with a user. |
33 | b18ef3ad | Antony Chazapis | \ List shared containers/objects. |
34 | 66f6dfc2 | Antony Chazapis | \ Update implementation guidelines. |
35 | a8326bef | Antony Chazapis | \ Check preconditions when creating/updating objects. |
36 | 7b0688a9 | Sofia Papagiannaki | 0.4 (July 01, 2011) Object permissions and account groups. |
37 | 3ab38c43 | Antony Chazapis | \ Control versioning behavior and container quotas with container policy directives. |
38 | 3ab38c43 | Antony Chazapis | \ Support updating/deleting individual metadata with ``POST``. |
39 | 7b0688a9 | Sofia Papagiannaki | \ Create object using hashmap. |
40 | 8cb45c13 | Antony Chazapis | 0.3 (June 14, 2011) Large object support with ``X-Object-Manifest``. |
41 | 8cb45c13 | Antony Chazapis | \ Allow for publicly available objects via ``https://hostname/public``. |
42 | c9af0703 | Antony Chazapis | \ Support time-variant account/container listings. |
43 | 1d5c57d3 | Antony Chazapis | \ Add source version when duplicating with ``PUT``/``COPY``. |
44 | 1d5c57d3 | Antony Chazapis | \ Request version in object ``HEAD``/``GET`` requests (list versions with ``GET``). |
45 | 6bc372a4 | Antony Chazapis | 0.2 (May 31, 2011) Add object meta listing and filtering in containers. |
46 | 6bc372a4 | Antony Chazapis | \ Include underlying storage characteristics in container meta. |
47 | 1d5c57d3 | Antony Chazapis | \ Support for partial object updates through ``POST``. |
48 | 1d5c57d3 | Antony Chazapis | \ Expose object hashmaps through ``GET``. |
49 | 1d5c57d3 | Antony Chazapis | \ Support for multi-range object ``GET`` requests. |
50 | f2d7b5ab | Antony Chazapis | 0.1 (May 17, 2011) Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011). |
51 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
52 | f2d7b5ab | Antony Chazapis | |
53 | f2d7b5ab | Antony Chazapis | The Pithos API |
54 | f2d7b5ab | Antony Chazapis | -------------- |
55 | f2d7b5ab | Antony Chazapis | |
56 | c9af0703 | Antony Chazapis | The URI requests supported by the Pithos API follow one of the following forms: |
57 | f2d7b5ab | Antony Chazapis | |
58 | f2d7b5ab | Antony Chazapis | * Top level: ``https://hostname/v1/`` |
59 | f2d7b5ab | Antony Chazapis | * Account level: ``https://hostname/v1/<account>`` |
60 | f2d7b5ab | Antony Chazapis | * Container level: ``https://hostname/v1/<account>/<container>`` |
61 | f2d7b5ab | Antony Chazapis | * Object level: ``https://hostname/v1/<account>/<container>/<object>`` |
62 | f2d7b5ab | Antony Chazapis | |
63 | 81f947fd | Antony Chazapis | All requests must include an ``X-Auth-Token`` - as a header, or a parameter. The process of obtaining the token is still to be determined (**TBD**). |
64 | f2d7b5ab | Antony Chazapis | |
65 | e9285524 | Antony Chazapis | The allowable request operations and respective return codes per level are presented in the remainder of this chapter. Common to all requests are the following return codes. |
66 | f2d7b5ab | Antony Chazapis | |
67 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
68 | f2d7b5ab | Antony Chazapis | Return Code Description |
69 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
70 | f2d7b5ab | Antony Chazapis | 400 (Bad Request) The request is invalid |
71 | f2d7b5ab | Antony Chazapis | 401 (Unauthorized) Request not allowed |
72 | f2d7b5ab | Antony Chazapis | 404 (Not Found) The requested resource was not found |
73 | f2d7b5ab | Antony Chazapis | 503 (Service Unavailable) The request cannot be completed because of an internal error |
74 | f2d7b5ab | Antony Chazapis | ========================= ================================ |
75 | f2d7b5ab | Antony Chazapis | |
76 | f2d7b5ab | Antony Chazapis | Top Level |
77 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^ |
78 | f2d7b5ab | Antony Chazapis | |
79 | f2d7b5ab | Antony Chazapis | List of operations: |
80 | f2d7b5ab | Antony Chazapis | |
81 | f2d7b5ab | Antony Chazapis | ========= ================== |
82 | f2d7b5ab | Antony Chazapis | Operation Description |
83 | f2d7b5ab | Antony Chazapis | ========= ================== |
84 | f6c97079 | Antony Chazapis | GET Authentication (for compatibility with the OOS API) or list allowed accounts |
85 | f2d7b5ab | Antony Chazapis | ========= ================== |
86 | f2d7b5ab | Antony Chazapis | |
87 | f2d7b5ab | Antony Chazapis | GET |
88 | f2d7b5ab | Antony Chazapis | """ |
89 | f2d7b5ab | Antony Chazapis | |
90 | f2d7b5ab | Antony Chazapis | If the ``X-Auth-User`` and ``X-Auth-Key`` headers are given, a dummy ``X-Auth-Token`` and ``X-Storage-Url`` will be replied, which can be used as a guest token/namespace for testing Pithos. |
91 | f2d7b5ab | Antony Chazapis | |
92 | f2d7b5ab | Antony Chazapis | ================ ===================== |
93 | f2d7b5ab | Antony Chazapis | Return Code Description |
94 | f2d7b5ab | Antony Chazapis | ================ ===================== |
95 | f2d7b5ab | Antony Chazapis | 204 (No Content) The request succeeded |
96 | f2d7b5ab | Antony Chazapis | ================ ===================== |
97 | f2d7b5ab | Antony Chazapis | |
98 | f6c97079 | Antony Chazapis | If an ``X-Auth-Token`` is already present, the operation will be interpreted as a request to list other accounts that share objects to the user. |
99 | f6c97079 | Antony Chazapis | |
100 | f6c97079 | Antony Chazapis | ====================== ========================= |
101 | f6c97079 | Antony Chazapis | Request Parameter Name Value |
102 | f6c97079 | Antony Chazapis | ====================== ========================= |
103 | f6c97079 | Antony Chazapis | limit The amount of results requested (default is 10000) |
104 | f6c97079 | Antony Chazapis | marker Return containers with name lexicographically after marker |
105 | f6c97079 | Antony Chazapis | format Optional extended reply type (can be ``json`` or ``xml``) |
106 | f6c97079 | Antony Chazapis | ====================== ========================= |
107 | f6c97079 | Antony Chazapis | |
108 | f6c97079 | Antony Chazapis | The reply is a list of account names. |
109 | bd590bc1 | Antony Chazapis | If a ``format=xml`` or ``format=json`` argument is given, extended information on the accounts will be returned, serialized in the chosen format. |
110 | f6c97079 | Antony Chazapis | For each account, the information will include the following (names will be in lower case and with hyphens replaced with underscores): |
111 | f6c97079 | Antony Chazapis | |
112 | f6c97079 | Antony Chazapis | =========================== ============================ |
113 | f6c97079 | Antony Chazapis | Name Description |
114 | f6c97079 | Antony Chazapis | =========================== ============================ |
115 | f6c97079 | Antony Chazapis | name The name of the account |
116 | bd590bc1 | Antony Chazapis | last_modified The last account modification date (regardless of ``until``) |
117 | f6c97079 | Antony Chazapis | =========================== ============================ |
118 | f6c97079 | Antony Chazapis | |
119 | f6c97079 | Antony Chazapis | Example ``format=json`` reply: |
120 | f6c97079 | Antony Chazapis | |
121 | f6c97079 | Antony Chazapis | :: |
122 | f6c97079 | Antony Chazapis | |
123 | f6c97079 | Antony Chazapis | [{"name": "user", "last_modified": "2011-07-19T10:48:16"}, ...] |
124 | f6c97079 | Antony Chazapis | |
125 | f6c97079 | Antony Chazapis | Example ``format=xml`` reply: |
126 | f6c97079 | Antony Chazapis | |
127 | f6c97079 | Antony Chazapis | :: |
128 | f6c97079 | Antony Chazapis | |
129 | f6c97079 | Antony Chazapis | <?xml version="1.0" encoding="UTF-8"?> |
130 | f6c97079 | Antony Chazapis | <accounts> |
131 | f6c97079 | Antony Chazapis | <account> |
132 | f6c97079 | Antony Chazapis | <name>user</name> |
133 | f6c97079 | Antony Chazapis | <last_modified>2011-07-19T10:48:16</last_modified> |
134 | f6c97079 | Antony Chazapis | </account> |
135 | f6c97079 | Antony Chazapis | <account>...</account> |
136 | f6c97079 | Antony Chazapis | </accounts> |
137 | f6c97079 | Antony Chazapis | |
138 | f6c97079 | Antony Chazapis | =========================== ===================== |
139 | f6c97079 | Antony Chazapis | Return Code Description |
140 | f6c97079 | Antony Chazapis | =========================== ===================== |
141 | f6c97079 | Antony Chazapis | 200 (OK) The request succeeded |
142 | bd590bc1 | Antony Chazapis | 204 (No Content) The user has no access to other accounts (only for non-extended replies) |
143 | f6c97079 | Antony Chazapis | =========================== ===================== |
144 | f6c97079 | Antony Chazapis | |
145 | f6c97079 | Antony Chazapis | Will use a ``200`` return code if the reply is of type json/xml. |
146 | f2d7b5ab | Antony Chazapis | |
147 | f2d7b5ab | Antony Chazapis | Account Level |
148 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^^^^^ |
149 | f2d7b5ab | Antony Chazapis | |
150 | f2d7b5ab | Antony Chazapis | List of operations: |
151 | f2d7b5ab | Antony Chazapis | |
152 | f2d7b5ab | Antony Chazapis | ========= ================== |
153 | f2d7b5ab | Antony Chazapis | Operation Description |
154 | f2d7b5ab | Antony Chazapis | ========= ================== |
155 | f2d7b5ab | Antony Chazapis | HEAD Retrieve account metadata |
156 | f2d7b5ab | Antony Chazapis | GET List containers |
157 | f2d7b5ab | Antony Chazapis | POST Update account metadata |
158 | f2d7b5ab | Antony Chazapis | ========= ================== |
159 | f2d7b5ab | Antony Chazapis | |
160 | f2d7b5ab | Antony Chazapis | HEAD |
161 | f2d7b5ab | Antony Chazapis | """" |
162 | f2d7b5ab | Antony Chazapis | |
163 | a8326bef | Antony Chazapis | ==================== =========================== |
164 | a8326bef | Antony Chazapis | Request Header Name Value |
165 | a8326bef | Antony Chazapis | ==================== =========================== |
166 | a8326bef | Antony Chazapis | If-Modified-Since Retrieve if account has changed since provided timestamp |
167 | a8326bef | Antony Chazapis | If-Unmodified-Since Retrieve if account has not changed since provided timestamp |
168 | a8326bef | Antony Chazapis | ==================== =========================== |
169 | a8326bef | Antony Chazapis | |
170 | a8326bef | Antony Chazapis | | |
171 | a8326bef | Antony Chazapis | |
172 | c9af0703 | Antony Chazapis | ====================== =================================== |
173 | c9af0703 | Antony Chazapis | Request Parameter Name Value |
174 | c9af0703 | Antony Chazapis | ====================== =================================== |
175 | c9af0703 | Antony Chazapis | until Optional timestamp |
176 | c9af0703 | Antony Chazapis | ====================== =================================== |
177 | c9af0703 | Antony Chazapis | |
178 | f6c97079 | Antony Chazapis | Cross-user requests are not allowed to use ``until`` and only include the account modification date in the reply. |
179 | f2d7b5ab | Antony Chazapis | |
180 | f2d7b5ab | Antony Chazapis | ========================== ===================== |
181 | f2d7b5ab | Antony Chazapis | Reply Header Name Value |
182 | f2d7b5ab | Antony Chazapis | ========================== ===================== |
183 | f2d7b5ab | Antony Chazapis | X-Account-Container-Count The total number of containers |
184 | f2d7b5ab | Antony Chazapis | X-Account-Object-Count The total number of objects (**TBD**) |
185 | f2d7b5ab | Antony Chazapis | X-Account-Bytes-Used The total number of bytes stored |
186 | f2d7b5ab | Antony Chazapis | X-Account-Bytes-Remaining The total number of bytes remaining (**TBD**) |
187 | f2d7b5ab | Antony Chazapis | X-Account-Last-Login The last login (**TBD**) |
188 | c9af0703 | Antony Chazapis | X-Account-Until-Timestamp The last account modification date until the timestamp provided |
189 | 3ab38c43 | Antony Chazapis | X-Account-Group-* Optional user defined groups |
190 | f2d7b5ab | Antony Chazapis | X-Account-Meta-* Optional user defined metadata |
191 | c9af0703 | Antony Chazapis | Last-Modified The last account modification date (regardless of ``until``) |
192 | f2d7b5ab | Antony Chazapis | ========================== ===================== |
193 | f2d7b5ab | Antony Chazapis | |
194 | f2d7b5ab | Antony Chazapis | | |
195 | f2d7b5ab | Antony Chazapis | |
196 | f2d7b5ab | Antony Chazapis | ================ ===================== |
197 | f2d7b5ab | Antony Chazapis | Return Code Description |
198 | f2d7b5ab | Antony Chazapis | ================ ===================== |
199 | f2d7b5ab | Antony Chazapis | 204 (No Content) The request succeeded |
200 | f2d7b5ab | Antony Chazapis | ================ ===================== |
201 | f2d7b5ab | Antony Chazapis | |
202 | f2d7b5ab | Antony Chazapis | |
203 | f2d7b5ab | Antony Chazapis | GET |
204 | f2d7b5ab | Antony Chazapis | """ |
205 | f2d7b5ab | Antony Chazapis | |
206 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
207 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
208 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
209 | f2d7b5ab | Antony Chazapis | If-Modified-Since Retrieve if account has changed since provided timestamp |
210 | f2d7b5ab | Antony Chazapis | If-Unmodified-Since Retrieve if account has not changed since provided timestamp |
211 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
212 | f2d7b5ab | Antony Chazapis | |
213 | f2d7b5ab | Antony Chazapis | | |
214 | f2d7b5ab | Antony Chazapis | |
215 | f2d7b5ab | Antony Chazapis | ====================== ========================= |
216 | f2d7b5ab | Antony Chazapis | Request Parameter Name Value |
217 | f2d7b5ab | Antony Chazapis | ====================== ========================= |
218 | f2d7b5ab | Antony Chazapis | limit The amount of results requested (default is 10000) |
219 | f2d7b5ab | Antony Chazapis | marker Return containers with name lexicographically after marker |
220 | f2d7b5ab | Antony Chazapis | format Optional extended reply type (can be ``json`` or ``xml``) |
221 | b18ef3ad | Antony Chazapis | shared Show only shared containers (no value parameter) |
222 | c9af0703 | Antony Chazapis | until Optional timestamp |
223 | f2d7b5ab | Antony Chazapis | ====================== ========================= |
224 | f2d7b5ab | Antony Chazapis | |
225 | f2d7b5ab | Antony Chazapis | The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included. |
226 | f6c97079 | Antony Chazapis | Cross-user requests are not allowed to use ``until`` and only include the account/container modification dates in the reply. |
227 | f6c97079 | Antony Chazapis | |
228 | f2d7b5ab | Antony Chazapis | If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format. |
229 | f2d7b5ab | Antony Chazapis | For each container, the information will include all container metadata (names will be in lower case and with hyphens replaced with underscores): |
230 | f2d7b5ab | Antony Chazapis | |
231 | c9af0703 | Antony Chazapis | =========================== ============================ |
232 | c9af0703 | Antony Chazapis | Name Description |
233 | c9af0703 | Antony Chazapis | =========================== ============================ |
234 | c9af0703 | Antony Chazapis | name The name of the container |
235 | c9af0703 | Antony Chazapis | count The number of objects inside the container |
236 | c9af0703 | Antony Chazapis | bytes The total size of the objects inside the container |
237 | c9af0703 | Antony Chazapis | last_modified The last container modification date (regardless of ``until``) |
238 | c9af0703 | Antony Chazapis | x_container_until_timestamp The last container modification date until the timestamp provided |
239 | 3ab38c43 | Antony Chazapis | x_container_policy_* Container behavior and limits |
240 | c9af0703 | Antony Chazapis | x_container_meta_* Optional user defined metadata |
241 | c9af0703 | Antony Chazapis | =========================== ============================ |
242 | f2d7b5ab | Antony Chazapis | |
243 | f2d7b5ab | Antony Chazapis | For examples of container details returned in JSON/XML formats refer to the OOS API documentation. |
244 | f2d7b5ab | Antony Chazapis | |
245 | 6bc372a4 | Antony Chazapis | =========================== ===================== |
246 | 6bc372a4 | Antony Chazapis | Return Code Description |
247 | 6bc372a4 | Antony Chazapis | =========================== ===================== |
248 | 6bc372a4 | Antony Chazapis | 200 (OK) The request succeeded |
249 | 6bc372a4 | Antony Chazapis | 204 (No Content) The account has no containers (only for non-extended replies) |
250 | 6bc372a4 | Antony Chazapis | 304 (Not Modified) The account has not been modified |
251 | 6bc372a4 | Antony Chazapis | 412 (Precondition Failed) The condition set can not be satisfied |
252 | 6bc372a4 | Antony Chazapis | =========================== ===================== |
253 | f2d7b5ab | Antony Chazapis | |
254 | f2d7b5ab | Antony Chazapis | Will use a ``200`` return code if the reply is of type json/xml. |
255 | f2d7b5ab | Antony Chazapis | |
256 | f2d7b5ab | Antony Chazapis | |
257 | f2d7b5ab | Antony Chazapis | POST |
258 | f2d7b5ab | Antony Chazapis | """" |
259 | f2d7b5ab | Antony Chazapis | |
260 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
261 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
262 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
263 | 3ab38c43 | Antony Chazapis | X-Account-Group-* Optional user defined groups |
264 | f2d7b5ab | Antony Chazapis | X-Account-Meta-* Optional user defined metadata |
265 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
266 | f2d7b5ab | Antony Chazapis | |
267 | a8326bef | Antony Chazapis | | |
268 | a8326bef | Antony Chazapis | |
269 | a8326bef | Antony Chazapis | ====================== ============================================ |
270 | a8326bef | Antony Chazapis | Request Parameter Name Value |
271 | a8326bef | Antony Chazapis | ====================== ============================================ |
272 | a8326bef | Antony Chazapis | update Do not replace metadata/groups (no value parameter) |
273 | a8326bef | Antony Chazapis | ====================== ============================================ |
274 | a8326bef | Antony Chazapis | |
275 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
276 | f2d7b5ab | Antony Chazapis | |
277 | a6eb13e9 | Antony Chazapis | The operation will overwrite all user defined metadata, except if ``update`` is defined. |
278 | 3ab38c43 | Antony Chazapis | To create a group, include an ``X-Account-Group-*`` header with the name in the key and a comma separated list of user names in the value. If no ``X-Account-Group-*`` header is present, no changes will be applied to groups. The ``update`` parameter also applies to groups. To delete a specific group, use ``update`` and an empty header value. |
279 | f2d7b5ab | Antony Chazapis | |
280 | f2d7b5ab | Antony Chazapis | ================ =============================== |
281 | f2d7b5ab | Antony Chazapis | Return Code Description |
282 | f2d7b5ab | Antony Chazapis | ================ =============================== |
283 | f2d7b5ab | Antony Chazapis | 202 (Accepted) The request has been accepted |
284 | f2d7b5ab | Antony Chazapis | ================ =============================== |
285 | f2d7b5ab | Antony Chazapis | |
286 | f2d7b5ab | Antony Chazapis | |
287 | f2d7b5ab | Antony Chazapis | Container Level |
288 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^^^^^^^ |
289 | f2d7b5ab | Antony Chazapis | |
290 | f2d7b5ab | Antony Chazapis | List of operations: |
291 | f2d7b5ab | Antony Chazapis | |
292 | f2d7b5ab | Antony Chazapis | ========= ============================ |
293 | f2d7b5ab | Antony Chazapis | Operation Description |
294 | f2d7b5ab | Antony Chazapis | ========= ============================ |
295 | f2d7b5ab | Antony Chazapis | HEAD Retrieve container metadata |
296 | f2d7b5ab | Antony Chazapis | GET List objects |
297 | f2d7b5ab | Antony Chazapis | PUT Create/update container |
298 | f2d7b5ab | Antony Chazapis | POST Update container metadata |
299 | f2d7b5ab | Antony Chazapis | DELETE Delete container |
300 | f2d7b5ab | Antony Chazapis | ========= ============================ |
301 | f2d7b5ab | Antony Chazapis | |
302 | f2d7b5ab | Antony Chazapis | |
303 | f2d7b5ab | Antony Chazapis | HEAD |
304 | f2d7b5ab | Antony Chazapis | """" |
305 | f2d7b5ab | Antony Chazapis | |
306 | a8326bef | Antony Chazapis | ==================== =========================== |
307 | a8326bef | Antony Chazapis | Request Header Name Value |
308 | a8326bef | Antony Chazapis | ==================== =========================== |
309 | a8326bef | Antony Chazapis | If-Modified-Since Retrieve if container has changed since provided timestamp |
310 | a8326bef | Antony Chazapis | If-Unmodified-Since Retrieve if container has not changed since provided timestamp |
311 | a8326bef | Antony Chazapis | ==================== =========================== |
312 | a8326bef | Antony Chazapis | |
313 | a8326bef | Antony Chazapis | | |
314 | a8326bef | Antony Chazapis | |
315 | c9af0703 | Antony Chazapis | ====================== =================================== |
316 | c9af0703 | Antony Chazapis | Request Parameter Name Value |
317 | c9af0703 | Antony Chazapis | ====================== =================================== |
318 | c9af0703 | Antony Chazapis | until Optional timestamp |
319 | c9af0703 | Antony Chazapis | ====================== =================================== |
320 | f2d7b5ab | Antony Chazapis | |
321 | f6c97079 | Antony Chazapis | Cross-user requests are not allowed to use ``until`` and only include the container modification date in the reply. |
322 | c9af0703 | Antony Chazapis | |
323 | c9af0703 | Antony Chazapis | =========================== =============================== |
324 | c9af0703 | Antony Chazapis | Reply Header Name Value |
325 | c9af0703 | Antony Chazapis | =========================== =============================== |
326 | c9af0703 | Antony Chazapis | X-Container-Object-Count The total number of objects in the container |
327 | c9af0703 | Antony Chazapis | X-Container-Bytes-Used The total number of bytes of all objects stored |
328 | c9af0703 | Antony Chazapis | X-Container-Block-Size The block size used by the storage backend |
329 | c9af0703 | Antony Chazapis | X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps |
330 | c9af0703 | Antony Chazapis | X-Container-Until-Timestamp The last container modification date until the timestamp provided |
331 | c9af0703 | Antony Chazapis | X-Container-Object-Meta A list with all meta keys used by objects |
332 | 3ab38c43 | Antony Chazapis | X-Container-Policy-* Container behavior and limits |
333 | c9af0703 | Antony Chazapis | X-Container-Meta-* Optional user defined metadata |
334 | c9af0703 | Antony Chazapis | Last-Modified The last container modification date (regardless of ``until``) |
335 | c9af0703 | Antony Chazapis | =========================== =============================== |
336 | f2d7b5ab | Antony Chazapis | |
337 | ca461a84 | Antony Chazapis | The keys returned in ``X-Container-Object-Meta`` are all the unique strings after the ``X-Object-Meta-`` prefix, formatted as a comma-separated list. See container ``PUT`` for a reference of policy directives. |
338 | f2d7b5ab | Antony Chazapis | |
339 | f2d7b5ab | Antony Chazapis | ================ =============================== |
340 | f2d7b5ab | Antony Chazapis | Return Code Description |
341 | f2d7b5ab | Antony Chazapis | ================ =============================== |
342 | f2d7b5ab | Antony Chazapis | 204 (No Content) The request succeeded |
343 | f2d7b5ab | Antony Chazapis | ================ =============================== |
344 | f2d7b5ab | Antony Chazapis | |
345 | f2d7b5ab | Antony Chazapis | |
346 | f2d7b5ab | Antony Chazapis | GET |
347 | f2d7b5ab | Antony Chazapis | """ |
348 | f2d7b5ab | Antony Chazapis | |
349 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
350 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
351 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
352 | f2d7b5ab | Antony Chazapis | If-Modified-Since Retrieve if container has changed since provided timestamp |
353 | f2d7b5ab | Antony Chazapis | If-Unmodified-Since Retrieve if container has not changed since provided timestamp |
354 | f2d7b5ab | Antony Chazapis | ==================== =========================== |
355 | f2d7b5ab | Antony Chazapis | |
356 | f2d7b5ab | Antony Chazapis | | |
357 | f2d7b5ab | Antony Chazapis | |
358 | f2d7b5ab | Antony Chazapis | ====================== =================================== |
359 | f2d7b5ab | Antony Chazapis | Request Parameter Name Value |
360 | f2d7b5ab | Antony Chazapis | ====================== =================================== |
361 | f2d7b5ab | Antony Chazapis | limit The amount of results requested (default is 10000) |
362 | f2d7b5ab | Antony Chazapis | marker Return containers with name lexicographically after marker |
363 | f2d7b5ab | Antony Chazapis | prefix Return objects starting with prefix |
364 | f2d7b5ab | Antony Chazapis | delimiter Return objects up to the delimiter (discussion follows) |
365 | f2d7b5ab | Antony Chazapis | path Assume ``prefix=path`` and ``delimiter=/`` |
366 | f2d7b5ab | Antony Chazapis | format Optional extended reply type (can be ``json`` or ``xml``) |
367 | f2d7b5ab | Antony Chazapis | meta Return objects having the specified meta keys (can be a comma separated list) |
368 | b18ef3ad | Antony Chazapis | shared Show only shared objects (no value parameter) |
369 | c9af0703 | Antony Chazapis | until Optional timestamp |
370 | f2d7b5ab | Antony Chazapis | ====================== =================================== |
371 | f2d7b5ab | Antony Chazapis | |
372 | f2d7b5ab | Antony Chazapis | The ``path`` parameter overrides ``prefix`` and ``delimiter``. When using ``path``, results will include objects ending in ``delimiter``. |
373 | f2d7b5ab | Antony Chazapis | |
374 | f2d7b5ab | Antony Chazapis | The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix. |
375 | f2d7b5ab | Antony Chazapis | |
376 | f2d7b5ab | Antony Chazapis | The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included. |
377 | f6c97079 | Antony Chazapis | Cross-user requests are not allowed to use ``until`` and include the following limited set of headers in the reply: |
378 | f6c97079 | Antony Chazapis | |
379 | f6c97079 | Antony Chazapis | =========================== =============================== |
380 | f6c97079 | Antony Chazapis | Reply Header Name Value |
381 | f6c97079 | Antony Chazapis | =========================== =============================== |
382 | f6c97079 | Antony Chazapis | X-Container-Block-Size The block size used by the storage backend |
383 | f6c97079 | Antony Chazapis | X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps |
384 | f6c97079 | Antony Chazapis | X-Container-Object-Meta A list with all meta keys used by allowed objects (**TBD**) |
385 | f6c97079 | Antony Chazapis | Last-Modified The last container modification date |
386 | f6c97079 | Antony Chazapis | =========================== =============================== |
387 | f6c97079 | Antony Chazapis | |
388 | f2d7b5ab | Antony Chazapis | If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format. |
389 | f2d7b5ab | Antony Chazapis | For each object, the information will include all object metadata (names will be in lower case and with hyphens replaced with underscores): |
390 | f2d7b5ab | Antony Chazapis | |
391 | c9af0703 | Antony Chazapis | ========================== ====================================== |
392 | c9af0703 | Antony Chazapis | Name Description |
393 | c9af0703 | Antony Chazapis | ========================== ====================================== |
394 | c9af0703 | Antony Chazapis | name The name of the object |
395 | c9af0703 | Antony Chazapis | hash The ETag of the object |
396 | c9af0703 | Antony Chazapis | bytes The size of the object |
397 | c9af0703 | Antony Chazapis | content_type The MIME content type of the object |
398 | c9af0703 | Antony Chazapis | content_encoding The encoding of the object (optional) |
399 | c9af0703 | Antony Chazapis | content-disposition The presentation style of the object (optional) |
400 | c9af0703 | Antony Chazapis | last_modified The last object modification date (regardless of version) |
401 | c9af0703 | Antony Chazapis | x_object_version The object's version identifier |
402 | c9af0703 | Antony Chazapis | x_object_version_timestamp The object's version timestamp |
403 | 104626e3 | Antony Chazapis | x_object_modified_by The user that committed the object's version |
404 | 6d817842 | Antony Chazapis | x_object_manifest Object parts prefix in ``<container>/<object>`` form (optional) |
405 | 3ab38c43 | Antony Chazapis | x_object_sharing Object permissions (optional) |
406 | 3ab38c43 | Antony Chazapis | x_object_shared_by Object inheriting permissions (optional) |
407 | 3ab38c43 | Antony Chazapis | x_object_public Object's publicly accessible URI (optional) |
408 | c9af0703 | Antony Chazapis | x_object_meta_* Optional user defined metadata |
409 | c9af0703 | Antony Chazapis | ========================== ====================================== |
410 | f2d7b5ab | Antony Chazapis | |
411 | f2d7b5ab | Antony Chazapis | Extended replies may also include virtual directory markers in separate sections of the ``json`` or ``xml`` results. |
412 | f2d7b5ab | Antony Chazapis | Virtual directory markers are only included when ``delimiter`` is explicitly set. They correspond to the substrings up to and including the first occurrence of the delimiter. |
413 | f2d7b5ab | Antony Chazapis | In JSON results they appear as dictionaries with only a ``"subdir"`` key. In XML results they appear interleaved with ``<object>`` tags as ``<subdir name="..." />``. |
414 | f2d7b5ab | Antony Chazapis | In case there is an object with the same name as a virtual directory marker, the object will be returned. |
415 | c9af0703 | Antony Chazapis | |
416 | f2d7b5ab | Antony Chazapis | For examples of object details returned in JSON/XML formats refer to the OOS API documentation. |
417 | f2d7b5ab | Antony Chazapis | |
418 | 6bc372a4 | Antony Chazapis | =========================== =============================== |
419 | 6bc372a4 | Antony Chazapis | Return Code Description |
420 | 6bc372a4 | Antony Chazapis | =========================== =============================== |
421 | 6bc372a4 | Antony Chazapis | 200 (OK) The request succeeded |
422 | 6bc372a4 | Antony Chazapis | 204 (No Content) The account has no containers (only for non-extended replies) |
423 | 6bc372a4 | Antony Chazapis | 304 (Not Modified) The container has not been modified |
424 | 6bc372a4 | Antony Chazapis | 412 (Precondition Failed) The condition set can not be satisfied |
425 | 6bc372a4 | Antony Chazapis | =========================== =============================== |
426 | f2d7b5ab | Antony Chazapis | |
427 | f2d7b5ab | Antony Chazapis | Will use a ``200`` return code if the reply is of type json/xml. |
428 | f2d7b5ab | Antony Chazapis | |
429 | f2d7b5ab | Antony Chazapis | |
430 | f2d7b5ab | Antony Chazapis | PUT |
431 | f2d7b5ab | Antony Chazapis | """ |
432 | f2d7b5ab | Antony Chazapis | |
433 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
434 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
435 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
436 | 3ab38c43 | Antony Chazapis | X-Container-Policy-* Container behavior and limits |
437 | f2d7b5ab | Antony Chazapis | X-Container-Meta-* Optional user defined metadata |
438 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
439 | f2d7b5ab | Antony Chazapis | |
440 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
441 | 3ab38c43 | Antony Chazapis | |
442 | 3ab38c43 | Antony Chazapis | If no policy is defined, the container will be created with the default values. |
443 | 3ab38c43 | Antony Chazapis | Available policy directives: |
444 | 3ab38c43 | Antony Chazapis | |
445 | 3ab38c43 | Antony Chazapis | * ``versioning``: Set to ``auto``, ``manual`` or ``none`` (default is ``manual``) |
446 | 3ab38c43 | Antony Chazapis | * ``quota``: Size limit in KB (default is ``0`` - unlimited) |
447 | f2d7b5ab | Antony Chazapis | |
448 | f2d7b5ab | Antony Chazapis | ================ =============================== |
449 | f2d7b5ab | Antony Chazapis | Return Code Description |
450 | f2d7b5ab | Antony Chazapis | ================ =============================== |
451 | f2d7b5ab | Antony Chazapis | 201 (Created) The container has been created |
452 | f2d7b5ab | Antony Chazapis | 202 (Accepted) The request has been accepted |
453 | f2d7b5ab | Antony Chazapis | ================ =============================== |
454 | f2d7b5ab | Antony Chazapis | |
455 | f2d7b5ab | Antony Chazapis | |
456 | f2d7b5ab | Antony Chazapis | POST |
457 | f2d7b5ab | Antony Chazapis | """" |
458 | f2d7b5ab | Antony Chazapis | |
459 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
460 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
461 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
462 | 3ab38c43 | Antony Chazapis | X-Container-Policy-* Container behavior and limits |
463 | f2d7b5ab | Antony Chazapis | X-Container-Meta-* Optional user defined metadata |
464 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
465 | f2d7b5ab | Antony Chazapis | |
466 | a8326bef | Antony Chazapis | | |
467 | a8326bef | Antony Chazapis | |
468 | a8326bef | Antony Chazapis | ====================== ============================================ |
469 | a8326bef | Antony Chazapis | Request Parameter Name Value |
470 | a8326bef | Antony Chazapis | ====================== ============================================ |
471 | a8326bef | Antony Chazapis | update Do not replace metadata/policy (no value parameter) |
472 | a8326bef | Antony Chazapis | ====================== ============================================ |
473 | a8326bef | Antony Chazapis | |
474 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
475 | f2d7b5ab | Antony Chazapis | |
476 | a6eb13e9 | Antony Chazapis | The operation will overwrite all user defined metadata, except if ``update`` is defined. |
477 | 3ab38c43 | Antony Chazapis | To change policy, include an ``X-Container-Policy-*`` header with the name in the key. If no ``X-Container-Policy-*`` header is present, no changes will be applied to policy. The ``update`` parameter also applies to policy - deleted values will revert to defaults. To delete/revert a specific policy directive, use ``update`` and an empty header value. See container ``PUT`` for a reference of policy directives. |
478 | f2d7b5ab | Antony Chazapis | |
479 | f2d7b5ab | Antony Chazapis | ================ =============================== |
480 | f2d7b5ab | Antony Chazapis | Return Code Description |
481 | f2d7b5ab | Antony Chazapis | ================ =============================== |
482 | f2d7b5ab | Antony Chazapis | 202 (Accepted) The request has been accepted |
483 | f2d7b5ab | Antony Chazapis | ================ =============================== |
484 | f2d7b5ab | Antony Chazapis | |
485 | f2d7b5ab | Antony Chazapis | |
486 | f2d7b5ab | Antony Chazapis | DELETE |
487 | f2d7b5ab | Antony Chazapis | """""" |
488 | f2d7b5ab | Antony Chazapis | |
489 | 81f947fd | Antony Chazapis | ====================== =================================== |
490 | 81f947fd | Antony Chazapis | Request Parameter Name Value |
491 | 81f947fd | Antony Chazapis | ====================== =================================== |
492 | 81f947fd | Antony Chazapis | until Optional timestamp |
493 | 81f947fd | Antony Chazapis | ====================== =================================== |
494 | 81f947fd | Antony Chazapis | |
495 | 81f947fd | Antony Chazapis | If ``until`` is defined, the container is "purged" up to that time (the history of all objects up to then is deleted). |
496 | f2d7b5ab | Antony Chazapis | |
497 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
498 | f2d7b5ab | Antony Chazapis | |
499 | f2d7b5ab | Antony Chazapis | ================ =============================== |
500 | f2d7b5ab | Antony Chazapis | Return Code Description |
501 | f2d7b5ab | Antony Chazapis | ================ =============================== |
502 | f2d7b5ab | Antony Chazapis | 204 (No Content) The request succeeded |
503 | f2d7b5ab | Antony Chazapis | 409 (Conflict) The container is not empty |
504 | f2d7b5ab | Antony Chazapis | ================ =============================== |
505 | f2d7b5ab | Antony Chazapis | |
506 | f2d7b5ab | Antony Chazapis | |
507 | f2d7b5ab | Antony Chazapis | Object Level |
508 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^^^^ |
509 | f2d7b5ab | Antony Chazapis | |
510 | f2d7b5ab | Antony Chazapis | List of operations: |
511 | f2d7b5ab | Antony Chazapis | |
512 | f2d7b5ab | Antony Chazapis | ========= ================================= |
513 | f2d7b5ab | Antony Chazapis | Operation Description |
514 | f2d7b5ab | Antony Chazapis | ========= ================================= |
515 | f2d7b5ab | Antony Chazapis | HEAD Retrieve object metadata |
516 | f2d7b5ab | Antony Chazapis | GET Read object data |
517 | f2d7b5ab | Antony Chazapis | PUT Write object data or copy/move object |
518 | f2d7b5ab | Antony Chazapis | COPY Copy object |
519 | f2d7b5ab | Antony Chazapis | MOVE Move object |
520 | 6bc372a4 | Antony Chazapis | POST Update object metadata/data |
521 | f2d7b5ab | Antony Chazapis | DELETE Delete object |
522 | f2d7b5ab | Antony Chazapis | ========= ================================= |
523 | f2d7b5ab | Antony Chazapis | |
524 | f2d7b5ab | Antony Chazapis | |
525 | f2d7b5ab | Antony Chazapis | HEAD |
526 | f2d7b5ab | Antony Chazapis | """" |
527 | f2d7b5ab | Antony Chazapis | |
528 | a8326bef | Antony Chazapis | ==================== ================================ |
529 | a8326bef | Antony Chazapis | Request Header Name Value |
530 | a8326bef | Antony Chazapis | ==================== ================================ |
531 | a8326bef | Antony Chazapis | If-Match Retrieve if ETags match |
532 | a8326bef | Antony Chazapis | If-None-Match Retrieve if ETags don't match |
533 | a8326bef | Antony Chazapis | If-Modified-Since Retrieve if object has changed since provided timestamp |
534 | a8326bef | Antony Chazapis | If-Unmodified-Since Retrieve if object has not changed since provided timestamp |
535 | a8326bef | Antony Chazapis | ==================== ================================ |
536 | a8326bef | Antony Chazapis | |
537 | a8326bef | Antony Chazapis | | |
538 | a8326bef | Antony Chazapis | |
539 | c9af0703 | Antony Chazapis | ====================== =================================== |
540 | c9af0703 | Antony Chazapis | Request Parameter Name Value |
541 | c9af0703 | Antony Chazapis | ====================== =================================== |
542 | c9af0703 | Antony Chazapis | version Optional version identifier |
543 | c9af0703 | Antony Chazapis | ====================== =================================== |
544 | c9af0703 | Antony Chazapis | |
545 | c9af0703 | Antony Chazapis | | |
546 | f2d7b5ab | Antony Chazapis | |
547 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
548 | f2d7b5ab | Antony Chazapis | Reply Header Name Value |
549 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
550 | e9285524 | Antony Chazapis | ETag The ETag of the object |
551 | f2d7b5ab | Antony Chazapis | Content-Length The size of the object |
552 | f2d7b5ab | Antony Chazapis | Content-Type The MIME content type of the object |
553 | c9af0703 | Antony Chazapis | Last-Modified The last object modification date (regardless of version) |
554 | f2d7b5ab | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
555 | f2d7b5ab | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
556 | c9af0703 | Antony Chazapis | X-Object-Version The object's version identifier |
557 | c9af0703 | Antony Chazapis | X-Object-Version-Timestamp The object's version timestamp |
558 | 104626e3 | Antony Chazapis | X-Object-Modified-By The user that comitted the object's version |
559 | 6d817842 | Antony Chazapis | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
560 | 3ab38c43 | Antony Chazapis | X-Object-Sharing Object permissions (optional) |
561 | 3ab38c43 | Antony Chazapis | X-Object-Shared-By Object inheriting permissions (optional) |
562 | 3ab38c43 | Antony Chazapis | X-Object-Public Object's publicly accessible URI (optional) |
563 | f2d7b5ab | Antony Chazapis | X-Object-Meta-* Optional user defined metadata |
564 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
565 | f2d7b5ab | Antony Chazapis | |
566 | f2d7b5ab | Antony Chazapis | | |
567 | f2d7b5ab | Antony Chazapis | |
568 | f2d7b5ab | Antony Chazapis | ================ =============================== |
569 | f2d7b5ab | Antony Chazapis | Return Code Description |
570 | f2d7b5ab | Antony Chazapis | ================ =============================== |
571 | cb146cf9 | Antony Chazapis | 200 (No Content) The request succeeded |
572 | f2d7b5ab | Antony Chazapis | ================ =============================== |
573 | f2d7b5ab | Antony Chazapis | |
574 | f2d7b5ab | Antony Chazapis | |
575 | f2d7b5ab | Antony Chazapis | GET |
576 | f2d7b5ab | Antony Chazapis | """ |
577 | f2d7b5ab | Antony Chazapis | |
578 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
579 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
580 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
581 | f2d7b5ab | Antony Chazapis | Range Optional range of data to retrieve |
582 | 7b0688a9 | Sofia Papagiannaki | If-Range Retrieve the missing part if entity is unchanged; otherwise, retrieve the entire new entity (used together with Range header) |
583 | f2d7b5ab | Antony Chazapis | If-Match Retrieve if ETags match |
584 | f2d7b5ab | Antony Chazapis | If-None-Match Retrieve if ETags don't match |
585 | f2d7b5ab | Antony Chazapis | If-Modified-Since Retrieve if object has changed since provided timestamp |
586 | f2d7b5ab | Antony Chazapis | If-Unmodified-Since Retrieve if object has not changed since provided timestamp |
587 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
588 | f2d7b5ab | Antony Chazapis | |
589 | e9285524 | Antony Chazapis | | |
590 | e9285524 | Antony Chazapis | |
591 | e9285524 | Antony Chazapis | ====================== =================================== |
592 | e9285524 | Antony Chazapis | Request Parameter Name Value |
593 | e9285524 | Antony Chazapis | ====================== =================================== |
594 | e9285524 | Antony Chazapis | format Optional extended reply type (can be ``json`` or ``xml``) |
595 | c9af0703 | Antony Chazapis | version Optional version identifier or ``list`` (specify a format if requesting a list) |
596 | e9285524 | Antony Chazapis | ====================== =================================== |
597 | e9285524 | Antony Chazapis | |
598 | c9af0703 | Antony Chazapis | The reply is the object's data (or part of it), except if a hashmap is requested with the ``format`` parameter, or a version list with ``version=list`` (in which case an extended reply format must be specified). Object headers (as in a ``HEAD`` request) are always included. |
599 | e9285524 | Antony Chazapis | |
600 | 6bc372a4 | Antony Chazapis | Hashmaps expose the underlying storage format of the object. Note that each hash is computed after trimming trailing null bytes of the corresponding block. |
601 | e9285524 | Antony Chazapis | |
602 | e9285524 | Antony Chazapis | Example ``format=json`` reply: |
603 | e9285524 | Antony Chazapis | |
604 | e9285524 | Antony Chazapis | :: |
605 | e9285524 | Antony Chazapis | |
606 | c9af0703 | Antony Chazapis | {"block_hash": "sha1", "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...], "block_size": 131072, "bytes": 242} |
607 | e9285524 | Antony Chazapis | |
608 | e9285524 | Antony Chazapis | Example ``format=xml`` reply: |
609 | e9285524 | Antony Chazapis | |
610 | e9285524 | Antony Chazapis | :: |
611 | e9285524 | Antony Chazapis | |
612 | e9285524 | Antony Chazapis | <?xml version="1.0" encoding="UTF-8"?> |
613 | 6bc372a4 | Antony Chazapis | <object name="file" bytes="24223726" block_size="131072" block_hash="sha1"> |
614 | e9285524 | Antony Chazapis | <hash>7295c41da03d7f916440b98e32c4a2a39351546c</hash> |
615 | e9285524 | Antony Chazapis | <hash>...</hash> |
616 | e9285524 | Antony Chazapis | </object> |
617 | f2d7b5ab | Antony Chazapis | |
618 | 104626e3 | Antony Chazapis | Version lists include the version identifier and timestamp for each available object version. Version identifiers can be arbitrary strings, so use the timestamp to find newer versions. |
619 | c9af0703 | Antony Chazapis | |
620 | c9af0703 | Antony Chazapis | Example ``format=json`` reply: |
621 | c9af0703 | Antony Chazapis | |
622 | c9af0703 | Antony Chazapis | :: |
623 | c9af0703 | Antony Chazapis | |
624 | c9af0703 | Antony Chazapis | {"versions": [[23, 1307700892], [28, 1307700898], ...]} |
625 | c9af0703 | Antony Chazapis | |
626 | c9af0703 | Antony Chazapis | Example ``format=xml`` reply: |
627 | c9af0703 | Antony Chazapis | |
628 | c9af0703 | Antony Chazapis | :: |
629 | c9af0703 | Antony Chazapis | |
630 | c9af0703 | Antony Chazapis | <?xml version="1.0" encoding="UTF-8"?> |
631 | c9af0703 | Antony Chazapis | <object name="file"> |
632 | c9af0703 | Antony Chazapis | <version timestamp="1307700892">23</version> |
633 | c9af0703 | Antony Chazapis | <version timestamp="1307700898">28</version> |
634 | c9af0703 | Antony Chazapis | <version timestamp="...">...</version> |
635 | c9af0703 | Antony Chazapis | </object> |
636 | c9af0703 | Antony Chazapis | |
637 | f2d7b5ab | Antony Chazapis | The ``Range`` header may include multiple ranges, as outlined in RFC2616. Then the ``Content-Type`` of the reply will be ``multipart/byteranges`` and each part will include a ``Content-Range`` header. |
638 | f2d7b5ab | Antony Chazapis | |
639 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
640 | f2d7b5ab | Antony Chazapis | Reply Header Name Value |
641 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
642 | e9285524 | Antony Chazapis | ETag The ETag of the object |
643 | f2d7b5ab | Antony Chazapis | Content-Length The size of the data returned |
644 | f2d7b5ab | Antony Chazapis | Content-Type The MIME content type of the object |
645 | f2d7b5ab | Antony Chazapis | Content-Range The range of data included (only on a single range request) |
646 | c9af0703 | Antony Chazapis | Last-Modified The last object modification date (regardless of version) |
647 | f2d7b5ab | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
648 | f2d7b5ab | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
649 | c9af0703 | Antony Chazapis | X-Object-Version The object's version identifier |
650 | c9af0703 | Antony Chazapis | X-Object-Version-Timestamp The object's version timestamp |
651 | 104626e3 | Antony Chazapis | X-Object-Modified-By The user that comitted the object's version |
652 | 6d817842 | Antony Chazapis | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
653 | 3ab38c43 | Antony Chazapis | X-Object-Sharing Object permissions (optional) |
654 | 3ab38c43 | Antony Chazapis | X-Object-Shared-By Object inheriting permissions (optional) |
655 | 3ab38c43 | Antony Chazapis | X-Object-Public Object's publicly accessible URI (optional) |
656 | f2d7b5ab | Antony Chazapis | X-Object-Meta-* Optional user defined metadata |
657 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
658 | f2d7b5ab | Antony Chazapis | |
659 | f2d7b5ab | Antony Chazapis | | |
660 | f2d7b5ab | Antony Chazapis | |
661 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
662 | f2d7b5ab | Antony Chazapis | Return Code Description |
663 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
664 | f2d7b5ab | Antony Chazapis | 200 (OK) The request succeeded |
665 | f2d7b5ab | Antony Chazapis | 206 (Partial Content) The range request succeeded |
666 | f2d7b5ab | Antony Chazapis | 304 (Not Modified) The object has not been modified |
667 | f2d7b5ab | Antony Chazapis | 412 (Precondition Failed) The condition set can not be satisfied |
668 | f2d7b5ab | Antony Chazapis | 416 (Range Not Satisfiable) The requested range is out of limits |
669 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
670 | f2d7b5ab | Antony Chazapis | |
671 | f2d7b5ab | Antony Chazapis | |
672 | f2d7b5ab | Antony Chazapis | PUT |
673 | f2d7b5ab | Antony Chazapis | """ |
674 | f2d7b5ab | Antony Chazapis | |
675 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
676 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
677 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
678 | a8326bef | Antony Chazapis | If-Match Put if ETags match with current object |
679 | a8326bef | Antony Chazapis | If-None-Match Put if ETags don't match with current object |
680 | f2d7b5ab | Antony Chazapis | ETag The MD5 hash of the object (optional to check written data) |
681 | f2d7b5ab | Antony Chazapis | Content-Length The size of the data written |
682 | f2d7b5ab | Antony Chazapis | Content-Type The MIME content type of the object |
683 | f2d7b5ab | Antony Chazapis | Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored) |
684 | f2d7b5ab | Antony Chazapis | X-Copy-From The source path in the form ``/<container>/<object>`` |
685 | f2d7b5ab | Antony Chazapis | X-Move-From The source path in the form ``/<container>/<object>`` |
686 | cb146cf9 | Antony Chazapis | X-Source-Version The source version to copy from |
687 | f2d7b5ab | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
688 | f2d7b5ab | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
689 | 6d817842 | Antony Chazapis | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
690 | 3ab38c43 | Antony Chazapis | X-Object-Sharing Object permissions (optional) |
691 | 3ab38c43 | Antony Chazapis | X-Object-Public Object is publicly accessible (optional) |
692 | f2d7b5ab | Antony Chazapis | X-Object-Meta-* Optional user defined metadata |
693 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
694 | f2d7b5ab | Antony Chazapis | |
695 | f2d7b5ab | Antony Chazapis | | |
696 | f2d7b5ab | Antony Chazapis | |
697 | 7b0688a9 | Sofia Papagiannaki | ====================== =================================== |
698 | 7b0688a9 | Sofia Papagiannaki | Request Parameter Name Value |
699 | 7b0688a9 | Sofia Papagiannaki | ====================== =================================== |
700 | 7b0688a9 | Sofia Papagiannaki | format Optional extended request type (can be ``json``) to create the object by suppling its hashmap instead |
701 | 7b0688a9 | Sofia Papagiannaki | ====================== =================================== |
702 | 7b0688a9 | Sofia Papagiannaki | |
703 | 1d5c57d3 | Antony Chazapis | The request is the object's data (or part of it), except if a hashmap is provided with the ``format`` parameter. If format is used and all different parts are stored in the server, the object is created, otherwise the server returns Conflict (409) with the list of the missing parts. |
704 | 7b0688a9 | Sofia Papagiannaki | |
705 | 7b0688a9 | Sofia Papagiannaki | Hashmaps expose the underlying storage format of the object. |
706 | 7b0688a9 | Sofia Papagiannaki | |
707 | 7b0688a9 | Sofia Papagiannaki | Example ``format=json`` request: |
708 | 7b0688a9 | Sofia Papagiannaki | |
709 | 7b0688a9 | Sofia Papagiannaki | :: |
710 | 7b0688a9 | Sofia Papagiannaki | |
711 | 7b0688a9 | Sofia Papagiannaki | {"block_hash": "sha1", "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...], "block_size": 131072, "bytes": 242} |
712 | 7b0688a9 | Sofia Papagiannaki | |
713 | 32a437b1 | Sofia Papagiannaki | Example ``format=xml`` request: |
714 | 32a437b1 | Sofia Papagiannaki | |
715 | 32a437b1 | Sofia Papagiannaki | :: |
716 | 32a437b1 | Sofia Papagiannaki | |
717 | 32a437b1 | Sofia Papagiannaki | <?xml version="1.0" encoding="UTF-8"?> |
718 | 32a437b1 | Sofia Papagiannaki | <object name="file" bytes="24223726" block_size="131072" block_hash="sha1"> |
719 | 32a437b1 | Sofia Papagiannaki | <hash>7295c41da03d7f916440b98e32c4a2a39351546c</hash> |
720 | 32a437b1 | Sofia Papagiannaki | <hash>...</hash> |
721 | 32a437b1 | Sofia Papagiannaki | </object> |
722 | 7b0688a9 | Sofia Papagiannaki | |
723 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
724 | f2d7b5ab | Antony Chazapis | Reply Header Name Value |
725 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
726 | f2d7b5ab | Antony Chazapis | ETag The MD5 hash of the object (on create) |
727 | f2d7b5ab | Antony Chazapis | ========================== =============================== |
728 | f2d7b5ab | Antony Chazapis | |
729 | b0a2d1a6 | Antony Chazapis | The ``X-Object-Sharing`` header may include either a ``read=...`` comma-separated user/group list, or a ``write=...`` comma-separated user/group list, or both separated by a semicolon (``;``). Groups are specified as ``<account>:<group>``. To publish the object, set ``X-Object-Public`` to ``true``. To unpublish, set to ``false``, or use an empty header value. |
730 | f2d7b5ab | Antony Chazapis | |
731 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
732 | f2d7b5ab | Antony Chazapis | Return Code Description |
733 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
734 | f2d7b5ab | Antony Chazapis | 201 (Created) The object has been created |
735 | 1993fea9 | Antony Chazapis | 409 (Conflict) The object can not be created from the provided hashmap, or there are conflicting permissions (a list of missing hashes, or a conflicting sharing path will be included in the reply - in JSON format) |
736 | f2d7b5ab | Antony Chazapis | 411 (Length Required) Missing ``Content-Length`` or ``Content-Type`` in the request |
737 | f2d7b5ab | Antony Chazapis | 422 (Unprocessable Entity) The MD5 checksum of the data written to the storage system does not match the (optionally) supplied ETag value |
738 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
739 | f2d7b5ab | Antony Chazapis | |
740 | f2d7b5ab | Antony Chazapis | |
741 | f2d7b5ab | Antony Chazapis | COPY |
742 | f2d7b5ab | Antony Chazapis | """" |
743 | f2d7b5ab | Antony Chazapis | |
744 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
745 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
746 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
747 | a8326bef | Antony Chazapis | If-Match Proceed if ETags match with object |
748 | a8326bef | Antony Chazapis | If-None-Match Proceed if ETags don't match with object |
749 | f2d7b5ab | Antony Chazapis | Destination The destination path in the form ``/<container>/<object>`` |
750 | f2d7b5ab | Antony Chazapis | Content-Type The MIME content type of the object (optional) |
751 | f2d7b5ab | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
752 | f2d7b5ab | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
753 | cb146cf9 | Antony Chazapis | X-Source-Version The source version to copy from |
754 | 6d817842 | Antony Chazapis | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
755 | 3ab38c43 | Antony Chazapis | X-Object-Sharing Object permissions (optional) |
756 | 3ab38c43 | Antony Chazapis | X-Object-Public Object is publicly accessible (optional) |
757 | f2d7b5ab | Antony Chazapis | X-Object-Meta-* Optional user defined metadata |
758 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
759 | f2d7b5ab | Antony Chazapis | |
760 | 3ab38c43 | Antony Chazapis | Refer to ``PUT``/``POST`` for a description of request headers. Metadata is also copied, updated with any values defined. Sharing/publishing options are not copied. |
761 | a6eb13e9 | Antony Chazapis | |
762 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
763 | f2d7b5ab | Antony Chazapis | |
764 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
765 | f2d7b5ab | Antony Chazapis | Return Code Description |
766 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
767 | f2d7b5ab | Antony Chazapis | 201 (Created) The object has been created |
768 | 1993fea9 | Antony Chazapis | 409 (Conflict) There are conflicting permissions (a conflicting sharing path will be included in the reply - in JSON format) |
769 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
770 | f2d7b5ab | Antony Chazapis | |
771 | f2d7b5ab | Antony Chazapis | |
772 | f2d7b5ab | Antony Chazapis | MOVE |
773 | f2d7b5ab | Antony Chazapis | """" |
774 | f2d7b5ab | Antony Chazapis | |
775 | cb146cf9 | Antony Chazapis | Same as ``COPY``, without the ``X-Source-Version`` request header. The ``MOVE`` operation is always applied on the latest version. |
776 | f2d7b5ab | Antony Chazapis | |
777 | f2d7b5ab | Antony Chazapis | |
778 | f2d7b5ab | Antony Chazapis | POST |
779 | f2d7b5ab | Antony Chazapis | """" |
780 | f2d7b5ab | Antony Chazapis | |
781 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
782 | f2d7b5ab | Antony Chazapis | Request Header Name Value |
783 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
784 | a8326bef | Antony Chazapis | If-Match Proceed if ETags match with object |
785 | a8326bef | Antony Chazapis | If-None-Match Proceed if ETags don't match with object |
786 | e9285524 | Antony Chazapis | Content-Length The size of the data written (optional, to update) |
787 | e9285524 | Antony Chazapis | Content-Type The MIME content type of the object (optional, to update) |
788 | e9285524 | Antony Chazapis | Content-Range The range of data supplied (optional, to update) |
789 | e9285524 | Antony Chazapis | Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored) |
790 | f2d7b5ab | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
791 | f2d7b5ab | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
792 | ab2e317e | Antony Chazapis | X-Source-Object Update with data from the object at path ``/<container>/<object>`` (optional, to update) |
793 | ab2e317e | Antony Chazapis | X-Source-Version The source version to update from (optional, to update) |
794 | 1495b972 | Antony Chazapis | X-Object-Bytes The updated object's final size (optional, when updating) |
795 | 6d817842 | Antony Chazapis | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
796 | 3ab38c43 | Antony Chazapis | X-Object-Sharing Object permissions (optional) |
797 | 3ab38c43 | Antony Chazapis | X-Object-Public Object is publicly accessible (optional) |
798 | f2d7b5ab | Antony Chazapis | X-Object-Meta-* Optional user defined metadata |
799 | f2d7b5ab | Antony Chazapis | ==================== ================================ |
800 | f2d7b5ab | Antony Chazapis | |
801 | a8326bef | Antony Chazapis | | |
802 | a8326bef | Antony Chazapis | |
803 | a8326bef | Antony Chazapis | ====================== ============================================ |
804 | a8326bef | Antony Chazapis | Request Parameter Name Value |
805 | a8326bef | Antony Chazapis | ====================== ============================================ |
806 | a8326bef | Antony Chazapis | update Do not replace metadata (no value parameter) |
807 | a8326bef | Antony Chazapis | ====================== ============================================ |
808 | a8326bef | Antony Chazapis | |
809 | 3ab38c43 | Antony Chazapis | The ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest`` and ``X-Object-Meta-*`` headers are considered to be user defined metadata. An operation without the ``update`` parameter will overwrite all previous values and remove any keys not supplied. When using ``update`` any metadata with an empty value will be deleted. |
810 | 3ab38c43 | Antony Chazapis | |
811 | 3ab38c43 | Antony Chazapis | To change permissions, include an ``X-Object-Sharing`` header (as defined in ``PUT``). To publish, include an ``X-Object-Public`` header, with a value of ``true``. If no such headers are defined, no changes will be applied to sharing/public. Use empty values to remove permissions/unpublish (unpublishing also works with ``false`` as a header value). Sharing options are applied to the object - not its versions. |
812 | e9285524 | Antony Chazapis | |
813 | a6eb13e9 | Antony Chazapis | To update an object's data: |
814 | e9285524 | Antony Chazapis | |
815 | ab2e317e | Antony Chazapis | * Either set ``Content-Type`` to ``application/octet-stream``, or provide an object with ``X-Source-Object``. If ``Content-Type`` has some other value, it will be ignored and only the metadata will be updated. |
816 | ab2e317e | Antony Chazapis | * If the data is supplied in the request (using ``Content-Type`` instead of ``X-Source-Object``), a valid ``Content-Length`` header is required - except if using chunked transfers (set ``Transfer-Encoding`` to ``chunked``). |
817 | e9285524 | Antony Chazapis | * Set ``Content-Range`` as specified in RFC2616, with the following differences: |
818 | e9285524 | Antony Chazapis | |
819 | e9285524 | Antony Chazapis | * Client software MAY omit ``last-byte-pos`` of if the length of the range being transferred is unknown or difficult to determine. |
820 | e9285524 | Antony Chazapis | * Client software SHOULD not specify the ``instance-length`` (use a ``*``), unless there is a reason for performing a size check at the server. |
821 | ab2e317e | Antony Chazapis | * If ``Content-Range`` used has a ``byte-range-resp-spec = *``, data will be appended to the object. |
822 | e9285524 | Antony Chazapis | |
823 | 1495b972 | Antony Chazapis | Optionally, truncate the updated object to the desired length with the ``X-Object-Bytes`` header. |
824 | 1495b972 | Antony Chazapis | |
825 | e9285524 | Antony Chazapis | A data update will trigger an ETag change. The new ETag will not correspond to the object's MD5 sum (**TBD**) and will be included in reply headers. |
826 | f2d7b5ab | Antony Chazapis | |
827 | e9285524 | Antony Chazapis | No reply content. No reply headers if only metadata is updated. |
828 | e9285524 | Antony Chazapis | |
829 | e9285524 | Antony Chazapis | ========================== =============================== |
830 | e9285524 | Antony Chazapis | Reply Header Name Value |
831 | e9285524 | Antony Chazapis | ========================== =============================== |
832 | e9285524 | Antony Chazapis | ETag The new ETag of the object (data updated) |
833 | e9285524 | Antony Chazapis | ========================== =============================== |
834 | e9285524 | Antony Chazapis | |
835 | e9285524 | Antony Chazapis | | |
836 | f2d7b5ab | Antony Chazapis | |
837 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
838 | f2d7b5ab | Antony Chazapis | Return Code Description |
839 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
840 | e9285524 | Antony Chazapis | 202 (Accepted) The request has been accepted (not a data update) |
841 | e9285524 | Antony Chazapis | 204 (No Content) The request succeeded (data updated) |
842 | 1993fea9 | Antony Chazapis | 409 (Conflict) There are conflicting permissions (a conflicting sharing path will be included in the reply - in JSON format) |
843 | d8d07c08 | Antony Chazapis | 411 (Length Required) Missing ``Content-Length`` in the request |
844 | a6eb13e9 | Antony Chazapis | 416 (Range Not Satisfiable) The supplied range is invalid |
845 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
846 | f2d7b5ab | Antony Chazapis | |
847 | 1d5c57d3 | Antony Chazapis | The ``POST`` method can also be used for creating an object via a standard HTML form. If the request ``Content-Type`` is ``multipart/form-data``, none of the above headers will be processed. The form should have exactly two fields, as in the following example. :: |
848 | 1d5c57d3 | Antony Chazapis | |
849 | 1d5c57d3 | Antony Chazapis | <form method="post" action="https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt" enctype="multipart/form-data"> |
850 | 1d5c57d3 | Antony Chazapis | <input type="hidden" name="X-Auth-Token" value="0000"> |
851 | 1d5c57d3 | Antony Chazapis | <input type="file" name="X-Object-Data"> |
852 | 1d5c57d3 | Antony Chazapis | <input type="submit"> |
853 | 1d5c57d3 | Antony Chazapis | </form> |
854 | 1d5c57d3 | Antony Chazapis | |
855 | 1d5c57d3 | Antony Chazapis | This will create/override the object with the given name, as if using ``PUT``. The ``Content-Type`` of the object will be set to the value of the corresponding header sent in the part of the request containing the data. Metadata, sharing and other object attributes can not be set this way. |
856 | 1d5c57d3 | Antony Chazapis | |
857 | 1d5c57d3 | Antony Chazapis | ========================== =============================== |
858 | 1d5c57d3 | Antony Chazapis | Reply Header Name Value |
859 | 1d5c57d3 | Antony Chazapis | ========================== =============================== |
860 | 1d5c57d3 | Antony Chazapis | ETag The MD5 hash of the object |
861 | 1d5c57d3 | Antony Chazapis | ========================== =============================== |
862 | 1d5c57d3 | Antony Chazapis | |
863 | 1d5c57d3 | Antony Chazapis | | |
864 | 1d5c57d3 | Antony Chazapis | |
865 | 1d5c57d3 | Antony Chazapis | =========================== ============================== |
866 | 1d5c57d3 | Antony Chazapis | Return Code Description |
867 | 1d5c57d3 | Antony Chazapis | =========================== ============================== |
868 | 1d5c57d3 | Antony Chazapis | 201 (Created) The object has been created |
869 | 1d5c57d3 | Antony Chazapis | =========================== ============================== |
870 | 1d5c57d3 | Antony Chazapis | |
871 | f2d7b5ab | Antony Chazapis | |
872 | f2d7b5ab | Antony Chazapis | DELETE |
873 | f2d7b5ab | Antony Chazapis | """""" |
874 | f2d7b5ab | Antony Chazapis | |
875 | 81f947fd | Antony Chazapis | ====================== =================================== |
876 | 81f947fd | Antony Chazapis | Request Parameter Name Value |
877 | 81f947fd | Antony Chazapis | ====================== =================================== |
878 | 81f947fd | Antony Chazapis | until Optional timestamp |
879 | 81f947fd | Antony Chazapis | ====================== =================================== |
880 | 81f947fd | Antony Chazapis | |
881 | 81f947fd | Antony Chazapis | If ``until`` is defined, the object is "purged" up to that time (the history up to then is deleted). |
882 | f2d7b5ab | Antony Chazapis | |
883 | f2d7b5ab | Antony Chazapis | No reply content/headers. |
884 | f2d7b5ab | Antony Chazapis | |
885 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
886 | f2d7b5ab | Antony Chazapis | Return Code Description |
887 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
888 | f2d7b5ab | Antony Chazapis | 204 (No Content) The request succeeded |
889 | f2d7b5ab | Antony Chazapis | =========================== ============================== |
890 | f2d7b5ab | Antony Chazapis | |
891 | 3ab38c43 | Antony Chazapis | Sharing and Public Objects |
892 | 3ab38c43 | Antony Chazapis | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
893 | 3ab38c43 | Antony Chazapis | |
894 | 3ab38c43 | Antony Chazapis | Read and write control in Pithos is managed by setting appropriate permissions with the ``X-Object-Sharing`` header. The permissions are applied using prefix-based inheritance. Thus, each set of authorization directives is applied to all objects sharing the same prefix with the object where the corresponding ``X-Object-Sharing`` header is defined. For simplicity, nested/overlapping permissions are not allowed. Setting ``X-Object-Sharing`` will fail, if the object is already "covered", or another object with a longer common-prefix name already has permissions. When retrieving an object, the ``X-Object-Shared-By`` header reports where it gets its permissions from. If not present, the object is the actual source of authorization directives. |
895 | c9af0703 | Antony Chazapis | |
896 | f6c97079 | Antony Chazapis | A user may ``GET`` another account or container. The result will include a limited reply, containing only the allowed containers or objects respectively. A top-level request with an authentication token, will return a list of allowed accounts, so the user can easily find out which other users share objects. |
897 | f6c97079 | Antony Chazapis | |
898 | f6c97079 | Antony Chazapis | Objects that are marked as public, via the ``X-Object-Public`` meta, are also available at the corresponding URI returned for ``HEAD`` or ``GET``. Requests for public objects do not need to include an ``X-Auth-Token``. Pithos will ignore request parameters and only include the following headers in the reply (all ``X-Object-*`` meta is hidden): |
899 | c9af0703 | Antony Chazapis | |
900 | c9af0703 | Antony Chazapis | ========================== =============================== |
901 | c9af0703 | Antony Chazapis | Reply Header Name Value |
902 | c9af0703 | Antony Chazapis | ========================== =============================== |
903 | c9af0703 | Antony Chazapis | ETag The ETag of the object |
904 | c9af0703 | Antony Chazapis | Content-Length The size of the data returned |
905 | c9af0703 | Antony Chazapis | Content-Type The MIME content type of the object |
906 | c9af0703 | Antony Chazapis | Content-Range The range of data included (only on a single range request) |
907 | c9af0703 | Antony Chazapis | Last-Modified The last object modification date (regardless of version) |
908 | c9af0703 | Antony Chazapis | Content-Encoding The encoding of the object (optional) |
909 | c9af0703 | Antony Chazapis | Content-Disposition The presentation style of the object (optional) |
910 | c9af0703 | Antony Chazapis | ========================== =============================== |
911 | f2d7b5ab | Antony Chazapis | |
912 | f6c97079 | Antony Chazapis | Public objects are not included and do not influence cross-user listings. They are, however, readable by all users. |
913 | f6c97079 | Antony Chazapis | |
914 | f2d7b5ab | Antony Chazapis | Summary |
915 | f2d7b5ab | Antony Chazapis | ^^^^^^^ |
916 | f2d7b5ab | Antony Chazapis | |
917 | f2d7b5ab | Antony Chazapis | List of differences from the OOS API: |
918 | f2d7b5ab | Antony Chazapis | |
919 | f2d7b5ab | Antony Chazapis | * Support for ``X-Account-Meta-*`` style headers at the account level. Use ``POST`` to update. |
920 | 3ab38c43 | Antony Chazapis | * Support for ``X-Container-Meta-*`` style headers at the container level. Can be set when creating via ``PUT``. Use ``POST`` to update. |
921 | f2d7b5ab | Antony Chazapis | * Header ``X-Container-Object-Meta`` at the container level and parameter ``meta`` in container listings. |
922 | 3ab38c43 | Antony Chazapis | * Container policies to manage behavior and limits. |
923 | 6bc372a4 | Antony Chazapis | * Headers ``X-Container-Block-*`` at the container level, exposing the underlying storage characteristics. |
924 | f2d7b5ab | Antony Chazapis | * All metadata replies, at all levels, include latest modification information. |
925 | a8326bef | Antony Chazapis | * At all levels, a ``HEAD`` or ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers. |
926 | b18ef3ad | Antony Chazapis | * Container/object lists include all associated metadata if the reply is of type json/xml. Some names are kept to their OOS API equivalents for compatibility. |
927 | b18ef3ad | Antony Chazapis | * Option to include only shared containers/objects in listings. |
928 | 3ab38c43 | Antony Chazapis | * Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``. These are all replaced with every update operation, except if using the ``update`` parameter (in which case individual keys can also be deleted). Deleting meta by providing empty values also works when copying/moving an object. |
929 | 1d5c57d3 | Antony Chazapis | * Multi-range object ``GET`` support as outlined in RFC2616. |
930 | 1d5c57d3 | Antony Chazapis | * Object hashmap retrieval through ``GET`` and the ``format`` parameter. |
931 | 1d5c57d3 | Antony Chazapis | * Object create via hashmap through ``PUT`` and the ``format`` parameter. |
932 | 1d5c57d3 | Antony Chazapis | * Object create using ``POST`` to support standard HTML forms. |
933 | 1d5c57d3 | Antony Chazapis | * Partial object updates through ``POST``, using the ``Content-Length``, ``Content-Type``, ``Content-Range`` and ``Transfer-Encoding`` headers. Use another object's data to update with ``X-Source-Object`` and ``X-Source-Version``. Truncate with ``X-Object-Bytes``. |
934 | f2d7b5ab | Antony Chazapis | * Object ``MOVE`` support. |
935 | a8326bef | Antony Chazapis | * Conditional object create/update operations, using ``If-Match`` and ``If-None-Match`` headers. |
936 | c9af0703 | Antony Chazapis | * Time-variant account/container listings via the ``until`` parameter. |
937 | 1d5c57d3 | Antony Chazapis | * Object versions - parameter ``version`` in ``HEAD``/``GET`` (list versions with ``GET``), ``X-Object-Version-*`` meta in replies, ``X-Source-Version`` in ``PUT``/``COPY``. |
938 | f6c97079 | Antony Chazapis | * Sharing/publishing with ``X-Object-Sharing``, ``X-Object-Public`` at the object level. Cross-user operations are allowed - controlled by sharing directives. Permissions may include groups defined with ``X-Account-Group-*`` at the account level. These apply to the object - not its versions. |
939 | 3ab38c43 | Antony Chazapis | * Support for prefix-based inheritance when enforcing permissions. Parent object carrying the authorization directives is reported in ``X-Object-Shared-By``. |
940 | 8cb45c13 | Antony Chazapis | * Large object support with ``X-Object-Manifest``. |
941 | 104626e3 | Antony Chazapis | * Trace the user that created/modified an object with ``X-Object-Modified-By``. |
942 | 81f947fd | Antony Chazapis | * Purge container/object history with the ``until`` parameter in ``DELETE``. |
943 | f2d7b5ab | Antony Chazapis | |
944 | f2d7b5ab | Antony Chazapis | Clarifications/suggestions: |
945 | f2d7b5ab | Antony Chazapis | |
946 | f2d7b5ab | Antony Chazapis | * Authentication is done by another system. The token is used in the same way, but it is obtained differently. The top level ``GET`` request is kept compatible with the OOS API and allows for guest/testing operations. |
947 | f2d7b5ab | Antony Chazapis | * Some processing is done in the variable part of all ``X-*-Meta-*`` headers. If it includes underscores, they will be converted to dashes and the first letter of all intra-dash strings will be capitalized. |
948 | f2d7b5ab | Antony Chazapis | * A ``GET`` reply for a level will include all headers of the corresponding ``HEAD`` request. |
949 | f2d7b5ab | Antony Chazapis | * To avoid conflicts between objects and virtual directory markers in container listings, it is recommended that object names do not end with the delimiter used. |
950 | 2938333b | Antony Chazapis | * The ``Accept`` header may be used in requests instead of the ``format`` parameter to specify the desired reply format. The parameter overrides the header (**TBD**). |
951 | f2d7b5ab | Antony Chazapis | * Container/object lists use a ``200`` return code if the reply is of type json/xml. The reply will include an empty json/xml. |
952 | 843d36d1 | Antony Chazapis | * In headers, dates are formatted according to RFC 1123. In extended information listings, the ``last_modified`` field is formatted according to ISO 8601 (for OOS API compatibility). All other fields (Pithos extensions) use integer tiemstamps. |
953 | c9af0703 | Antony Chazapis | * The ``Last-Modified`` header value always reflects the actual latest change timestamp, regardless of time control parameters and version requests. Time precondition checks with ``If-Modified-Since`` and ``If-Unmodified-Since`` headers are applied to this value. |
954 | a6eb13e9 | Antony Chazapis | * A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers. |
955 | 8cb45c13 | Antony Chazapis | * A ``HEAD`` or ``GET`` for an ``X-Object-Manifest`` object, will include modified ``Content-Length`` and ``ETag`` headers, according to the characteristics of the objects under the specified prefix. The ``Etag`` will be the MD5 hash of the corresponding ETags concatenated. In extended container listings there is no metadata processing. |
956 | f2d7b5ab | Antony Chazapis | |
957 | f2d7b5ab | Antony Chazapis | The Pithos Client |
958 | f2d7b5ab | Antony Chazapis | ----------------- |
959 | f2d7b5ab | Antony Chazapis | |
960 | f2d7b5ab | Antony Chazapis | User Experience |
961 | f2d7b5ab | Antony Chazapis | ^^^^^^^^^^^^^^^ |
962 | f2d7b5ab | Antony Chazapis | |
963 | f2d7b5ab | Antony Chazapis | Hopefully this API will allow for a multitude of client implementations, each supporting a different device or operating system. All clients will be able to manipulate containers and objects - even software only designed for OOS API compatibility. But a Pithos interface should not be only about showing containers and folders. There are some extra user interface elements and functionalities that should be common to all implementations. |
964 | f2d7b5ab | Antony Chazapis | |
965 | f2d7b5ab | Antony Chazapis | Upon entrance to the service, a user is presented with the following elements - which can be represented as folders or with other related icons: |
966 | f2d7b5ab | Antony Chazapis | |
967 | f2d7b5ab | Antony Chazapis | * The ``home`` element, which is used as the default entry point to the user's "files". Objects under ``home`` are represented in the usual hierarchical organization of folders and files. |
968 | f2d7b5ab | Antony Chazapis | * The ``trash`` element, which contains files that have been marked for deletion, but can still be recovered. |
969 | f2d7b5ab | Antony Chazapis | * The ``shared`` element, which contains all objects shared by the user to other users of the system. |
970 | f2d7b5ab | Antony Chazapis | * The ``others`` element, which contains all objects that other users share with the user. |
971 | f2d7b5ab | Antony Chazapis | * The ``tags`` element, which lists the names of tags the user has defined. This can be an entry point to list all files that have been assigned a specific tag or manage tags in general (remove a tag completely, rename a tag etc.). |
972 | f2d7b5ab | Antony Chazapis | * The ``groups`` element, which contains the names of groups the user has defined. Each group consists of a user list. Group creation, deletion, and manipulation is carried out by actions originating here. |
973 | 66f6dfc2 | Antony Chazapis | * The ``history`` element, which allows browsing past instances of ``home`` and - optionally - ``trash``. |
974 | f2d7b5ab | Antony Chazapis | |
975 | f2d7b5ab | Antony Chazapis | Objects in Pithos can be: |
976 | f2d7b5ab | Antony Chazapis | |
977 | f2d7b5ab | Antony Chazapis | * Assigned custom tags. |
978 | f2d7b5ab | Antony Chazapis | * Moved to trash and then deleted. |
979 | f2d7b5ab | Antony Chazapis | * Shared with specific permissions. |
980 | f2d7b5ab | Antony Chazapis | * Made public (shared with non-Pithos users). |
981 | c9af0703 | Antony Chazapis | * Restored from previous versions. |
982 | f2d7b5ab | Antony Chazapis | |
983 | 66f6dfc2 | Antony Chazapis | Some of these functions are performed by the client software and some by the Pithos server. |
984 | f2d7b5ab | Antony Chazapis | |
985 | 66f6dfc2 | Antony Chazapis | Implementation Guidelines |
986 | 66f6dfc2 | Antony Chazapis | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
987 | f2d7b5ab | Antony Chazapis | |
988 | a8326bef | Antony Chazapis | Pithos clients should use the ``pithos`` and ``trash`` containers for active and inactive objects respectively. If any of these containers is not found, the client software should create it, without interrupting the user's workflow. The ``home`` element corresponds to ``pithos`` and the ``trash`` element to ``trash``. Use ``PUT`` with the ``X-Move-From`` header, or ``MOVE`` to transfer objects from one container to the other. Use ``DELETE`` to remove from ``pithos`` without trashing, or to remove from ``trash``. When moving objects, detect naming conflicts with the ``If-Match`` or ``If-None-Match`` headers. Such conflicts should be resolved by the user. |
989 | f2d7b5ab | Antony Chazapis | |
990 | 66f6dfc2 | Antony Chazapis | Object names should use the ``/`` delimiter to impose a hierarchy of folders and files. |
991 | f2d7b5ab | Antony Chazapis | |
992 | 66f6dfc2 | Antony Chazapis | The ``shared`` element should be implemented as a read-only view of the ``pithos`` container, using the ``shared`` parameter when listing objects. The ``others`` element, should start with a top-level ``GET`` to retrieve the list of accounts accessible to the user. It is suggested that the client software hides the next step of navigation - the container - if it only includes ``pithos`` and forwards the user directly to the objects. |
993 | f2d7b5ab | Antony Chazapis | |
994 | 66f6dfc2 | Antony Chazapis | Public objects are not included in ``shared`` and ``others`` listings. It is suggested that they are marked in a visually distinctive way in ``pithos`` listings (for example using an icon overlay). |
995 | 66f6dfc2 | Antony Chazapis | |
996 | 66f6dfc2 | Antony Chazapis | At the object level, tags are implemented by managing metadata keys. The client software should allow the user to use any string as a tag and set the corresponding ``X-Object-Meta-<tag>`` key at the server. The API extensions provided, allow for listing all tags in a container and filtering object listings based on one or more tags. The tag list is sufficient for implementing the ``tags`` element, either as a special, virtual folder (as done in the first version of Pithos), or as an application menu. |
997 | 66f6dfc2 | Antony Chazapis | |
998 | 66f6dfc2 | Antony Chazapis | A special application menu, or a section in application preferences, should be devoted to managing groups (the ``groups`` element). All group-related actions are implemented at the account level. |
999 | 66f6dfc2 | Antony Chazapis | |
1000 | 66f6dfc2 | Antony Chazapis | Browsing past versions of objects should be available both at the object and the container level. At the object level, a list of past versions can be included in the screen showing details or more information on the object (metadata, tags, permissions, etc.). At the container level, it is suggested that clients use a ``history`` element, which presents to the user a read-only, time-variable view of ``pithos`` contents. This can be accomplished via the ``until`` parameter in listings. Optionally, ``history`` may include ``trash``. |
1001 | 288c1d55 | Antony Chazapis | |
1002 | 288c1d55 | Antony Chazapis | Recommended Practices and Examples |
1003 | 288c1d55 | Antony Chazapis | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
1004 | 288c1d55 | Antony Chazapis | |
1005 | 288c1d55 | Antony Chazapis | Assuming an authentication token is obtained (**TBD**), the following high-level operations are available - shown with ``curl``: |
1006 | 288c1d55 | Antony Chazapis | |
1007 | 288c1d55 | Antony Chazapis | * Get account information :: |
1008 | 288c1d55 | Antony Chazapis | |
1009 | 288c1d55 | Antony Chazapis | curl -X HEAD -D - \ |
1010 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1011 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user |
1012 | 288c1d55 | Antony Chazapis | |
1013 | 288c1d55 | Antony Chazapis | * List available containers :: |
1014 | 288c1d55 | Antony Chazapis | |
1015 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1016 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1017 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user |
1018 | 288c1d55 | Antony Chazapis | |
1019 | 288c1d55 | Antony Chazapis | * Get container information :: |
1020 | 288c1d55 | Antony Chazapis | |
1021 | 288c1d55 | Antony Chazapis | curl -X HEAD -D - \ |
1022 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1023 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos |
1024 | 288c1d55 | Antony Chazapis | |
1025 | 288c1d55 | Antony Chazapis | * Add a new container :: |
1026 | 288c1d55 | Antony Chazapis | |
1027 | 288c1d55 | Antony Chazapis | curl -X PUT -D - \ |
1028 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1029 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/test |
1030 | 288c1d55 | Antony Chazapis | |
1031 | 288c1d55 | Antony Chazapis | * Delete a container :: |
1032 | 288c1d55 | Antony Chazapis | |
1033 | 288c1d55 | Antony Chazapis | curl -X DELETE -D - \ |
1034 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1035 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/test |
1036 | 288c1d55 | Antony Chazapis | |
1037 | 288c1d55 | Antony Chazapis | * List objects in a container :: |
1038 | 288c1d55 | Antony Chazapis | |
1039 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1040 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1041 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos |
1042 | 288c1d55 | Antony Chazapis | |
1043 | 288c1d55 | Antony Chazapis | * List objects in a container (extended reply) :: |
1044 | 288c1d55 | Antony Chazapis | |
1045 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1046 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1047 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos?format=json |
1048 | 288c1d55 | Antony Chazapis | |
1049 | a6eb13e9 | Antony Chazapis | It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header. |
1050 | a6eb13e9 | Antony Chazapis | |
1051 | 288c1d55 | Antony Chazapis | * List metadata keys used by objects in a container |
1052 | 288c1d55 | Antony Chazapis | |
1053 | 288c1d55 | Antony Chazapis | Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``). |
1054 | 288c1d55 | Antony Chazapis | |
1055 | 288c1d55 | Antony Chazapis | * List objects in a container having a specific meta defined :: |
1056 | 288c1d55 | Antony Chazapis | |
1057 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1058 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1059 | ab2e317e | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos?meta=favorites |
1060 | 288c1d55 | Antony Chazapis | |
1061 | 288c1d55 | Antony Chazapis | * Retrieve an object :: |
1062 | 288c1d55 | Antony Chazapis | |
1063 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1064 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1065 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos/README.txt |
1066 | 288c1d55 | Antony Chazapis | |
1067 | 288c1d55 | Antony Chazapis | * Retrieve an object (specific ranges of data) :: |
1068 | 288c1d55 | Antony Chazapis | |
1069 | 288c1d55 | Antony Chazapis | curl -X GET -D - \ |
1070 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1071 | 288c1d55 | Antony Chazapis | -H "Range: bytes=0-9" \ |
1072 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos/README.txt |
1073 | 288c1d55 | Antony Chazapis | |
1074 | 288c1d55 | Antony Chazapis | This will return the first 10 bytes. To get the first 10, bytes 30-39 and the last 100 use ``Range: bytes=0-9,30-39,-100``. |
1075 | 288c1d55 | Antony Chazapis | |
1076 | 288c1d55 | Antony Chazapis | * Add a new object (folder type) (**TBD**) :: |
1077 | 288c1d55 | Antony Chazapis | |
1078 | 288c1d55 | Antony Chazapis | curl -X PUT -D - \ |
1079 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1080 | 288c1d55 | Antony Chazapis | -H "Content-Type: application/folder" \ |
1081 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos/folder |
1082 | 288c1d55 | Antony Chazapis | |
1083 | 288c1d55 | Antony Chazapis | * Add a new object :: |
1084 | 288c1d55 | Antony Chazapis | |
1085 | 288c1d55 | Antony Chazapis | curl -X PUT -D - \ |
1086 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1087 | 288c1d55 | Antony Chazapis | -H "Content-Type: text/plain" \ |
1088 | 288c1d55 | Antony Chazapis | -T EXAMPLE.txt |
1089 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/pithos/folder/EXAMPLE.txt |
1090 | 288c1d55 | Antony Chazapis | |
1091 | 288c1d55 | Antony Chazapis | * Update an object :: |
1092 | 288c1d55 | Antony Chazapis | |
1093 | 288c1d55 | Antony Chazapis | curl -X POST -D - \ |
1094 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1095 | 288c1d55 | Antony Chazapis | -H "Content-Length: 10" \ |
1096 | 288c1d55 | Antony Chazapis | -H "Content-Type: application/octet-stream" \ |
1097 | 288c1d55 | Antony Chazapis | -H "Content-Range: bytes 10-19/*" \ |
1098 | 288c1d55 | Antony Chazapis | -d "0123456789" \ |
1099 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |
1100 | 288c1d55 | Antony Chazapis | |
1101 | 288c1d55 | Antony Chazapis | This will update bytes 10-19 with the data specified. |
1102 | 288c1d55 | Antony Chazapis | |
1103 | 288c1d55 | Antony Chazapis | * Update an object (append) :: |
1104 | 288c1d55 | Antony Chazapis | |
1105 | 288c1d55 | Antony Chazapis | curl -X POST -D - \ |
1106 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1107 | 288c1d55 | Antony Chazapis | -H "Content-Length: 10" \ |
1108 | 288c1d55 | Antony Chazapis | -H "Content-Type: application/octet-stream" \ |
1109 | 288c1d55 | Antony Chazapis | -H "Content-Range: bytes */*" \ |
1110 | 288c1d55 | Antony Chazapis | -d "0123456789" \ |
1111 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |
1112 | 288c1d55 | Antony Chazapis | |
1113 | 1495b972 | Antony Chazapis | * Update an object (truncate) :: |
1114 | 1495b972 | Antony Chazapis | |
1115 | 1495b972 | Antony Chazapis | curl -X POST -D - \ |
1116 | 1495b972 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1117 | 1495b972 | Antony Chazapis | -H "X-Source-Object: /folder/EXAMPLE.txt" \ |
1118 | 1495b972 | Antony Chazapis | -H "Content-Range: bytes 0-0/*" \ |
1119 | 1495b972 | Antony Chazapis | -H "X-Object-Bytes: 0" \ |
1120 | 1495b972 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |
1121 | 1495b972 | Antony Chazapis | |
1122 | 1495b972 | Antony Chazapis | This will truncate the object to 0 bytes. |
1123 | 1495b972 | Antony Chazapis | |
1124 | 288c1d55 | Antony Chazapis | * Add object metadata :: |
1125 | 288c1d55 | Antony Chazapis | |
1126 | 288c1d55 | Antony Chazapis | curl -X POST -D - \ |
1127 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1128 | 288c1d55 | Antony Chazapis | -H "X-Object-Meta-First: first_meta_value" \ |
1129 | 288c1d55 | Antony Chazapis | -H "X-Object-Meta-Second: second_meta_value" \ |
1130 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |
1131 | 288c1d55 | Antony Chazapis | |
1132 | 288c1d55 | Antony Chazapis | * Delete object metadata :: |
1133 | 288c1d55 | Antony Chazapis | |
1134 | 288c1d55 | Antony Chazapis | curl -X POST -D - \ |
1135 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1136 | 288c1d55 | Antony Chazapis | -H "X-Object-Meta-First: first_meta_value" \ |
1137 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |
1138 | 288c1d55 | Antony Chazapis | |
1139 | 288c1d55 | Antony Chazapis | Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all metadata. |
1140 | 288c1d55 | Antony Chazapis | |
1141 | 288c1d55 | Antony Chazapis | * Delete an object :: |
1142 | 288c1d55 | Antony Chazapis | |
1143 | 288c1d55 | Antony Chazapis | curl -X DELETE -D - \ |
1144 | 288c1d55 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1145 | 288c1d55 | Antony Chazapis | https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt |