root / docs / pithos-api-guide.rst @ 62c0a9e1
History | View | Annotate | Download (69.9 kB)
1 | e5d8df8c | Constantinos Venetsanopoulos | Pithos API |
---|---|---|---|
2 | e5d8df8c | Constantinos Venetsanopoulos | ========== |
3 | 8f9976c6 | Constantinos Venetsanopoulos | |
4 | dad708b4 | Antony Chazapis | Introduction |
5 | dad708b4 | Antony Chazapis | ------------ |
6 | 8f9976c6 | Constantinos Venetsanopoulos | |
7 | dad708b4 | 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 | 8f9976c6 | Constantinos Venetsanopoulos | |
9 | dad708b4 | 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 | 8f9976c6 | Constantinos Venetsanopoulos | |
11 | dad708b4 | 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 | 8f9976c6 | Constantinos Venetsanopoulos | |
13 | 8f9976c6 | Constantinos Venetsanopoulos | This document's goals are: |
14 | 8f9976c6 | Constantinos Venetsanopoulos | |
15 | dad708b4 | Antony Chazapis | * Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls |
16 | dad708b4 | Antony Chazapis | * Specify metadata semantics and user interface guidelines for a common experience across client software implementations |
17 | dad708b4 | Antony Chazapis | |
18 | dad708b4 | 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 | 8f9976c6 | Constantinos Venetsanopoulos | |
20 | dad708b4 | Antony Chazapis | Whatever marked as to be determined (**TBD**), should not be considered by implementors. |
21 | 8f9976c6 | Constantinos Venetsanopoulos | |
22 | dad708b4 | Antony Chazapis | More info about Pithos can be found here: https://code.grnet.gr/projects/pithos |
23 | 8f9976c6 | Constantinos Venetsanopoulos | |
24 | 8f9976c6 | Constantinos Venetsanopoulos | Document Revisions |
25 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^^^^^^^^^^ |
26 | 8f9976c6 | Constantinos Venetsanopoulos | |
27 | 8f9976c6 | Constantinos Venetsanopoulos | ========================= ================================ |
28 | 8f9976c6 | Constantinos Venetsanopoulos | Revision Description |
29 | 8f9976c6 | Constantinos Venetsanopoulos | ========================= ================================ |
30 | c8860319 | Sofia Papagiannaki | 0.14 (Jun 18, 2013) Forbidden response for public listing by non path owners |
31 | 133e3fcf | Sofia Papagiannaki | 0.14 (Apr 23, 2013) Reply with Merkle hash in the ETag if MD5 is not computed. |
32 | 6fe32fb6 | Sofia Papagiannaki | 0.13 (Mar 27, 2013) Restrict public object listing only to the owner. |
33 | c8860319 | Sofia Papagiannaki | \ Do not propagate public URL information in shared objects. |
34 | dc068945 | Sofia Papagiannaki | 0.13 (Jan 21, 2013) Proxy identity management services |
35 | ff827ed3 | Sofia Papagiannaki | \ UUID to displayname translation |
36 | 87a157c1 | Sofia Papagiannaki | 0.10 (Jul 18, 2012) Support for bulk COPY/MOVE/DELETE |
37 | 87a157c1 | Sofia Papagiannaki | \ Optionally include public objects in listings. |
38 | 8f9976c6 | Constantinos Venetsanopoulos | 0.9 (Feb 17, 2012) Change permissions model. |
39 | 8f9976c6 | Constantinos Venetsanopoulos | \ Do not include user-defined metadata in account/container/object listings. |
40 | 8f9976c6 | Constantinos Venetsanopoulos | 0.8 (Jan 24, 2012) Update allowed versioning values. |
41 | 8f9976c6 | Constantinos Venetsanopoulos | \ Change policy/meta formatting in JSON/XML replies. |
42 | 8f9976c6 | Constantinos Venetsanopoulos | \ Document that all non-ASCII characters in headers should be URL-encoded. |
43 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support metadata-based queries when listing objects at the container level. |
44 | 8f9976c6 | Constantinos Venetsanopoulos | \ Note Content-Type issue when using the internal django web server. |
45 | 8f9976c6 | Constantinos Venetsanopoulos | \ Add object UUID field. |
46 | 8f9976c6 | Constantinos Venetsanopoulos | \ Always reply with the MD5 in the ETag. |
47 | 8f9976c6 | Constantinos Venetsanopoulos | \ Note that ``/login`` will only work if an external authentication system is defined. |
48 | 8f9976c6 | Constantinos Venetsanopoulos | \ Include option to ignore Content-Type on ``COPY``/``MOVE``. |
49 | 8f9976c6 | Constantinos Venetsanopoulos | \ Use format parameter for conflict (409) and uploaded hash list (container level) replies. |
50 | 8f9976c6 | Constantinos Venetsanopoulos | 0.7 (Nov 21, 2011) Suggest upload/download methods using hashmaps. |
51 | 8f9976c6 | Constantinos Venetsanopoulos | \ Propose syncing algorithm. |
52 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support cross-account object copy and move. |
53 | 8f9976c6 | Constantinos Venetsanopoulos | \ Pass token as a request parameter when using ``POST`` via an HTML form. |
54 | 8f9976c6 | Constantinos Venetsanopoulos | \ Optionally use source account to update object from another object. |
55 | 8f9976c6 | Constantinos Venetsanopoulos | \ Use container ``POST`` to upload missing blocks of data. |
56 | 8f9976c6 | Constantinos Venetsanopoulos | \ Report policy in account headers. |
57 | 8f9976c6 | Constantinos Venetsanopoulos | \ Add insufficient quota reply. |
58 | 8f9976c6 | Constantinos Venetsanopoulos | \ Use special meta to always report Merkle hash. |
59 | 8f9976c6 | Constantinos Venetsanopoulos | 0.6 (Sept 13, 2011) Reply with Merkle hash as the ETag when updating objects. |
60 | 8f9976c6 | Constantinos Venetsanopoulos | \ Include version id in object replace/change replies. |
61 | 8f9976c6 | Constantinos Venetsanopoulos | \ Change conflict (409) replies format to text. |
62 | 8f9976c6 | Constantinos Venetsanopoulos | \ Tags should be migrated to a meta value. |
63 | 8f9976c6 | Constantinos Venetsanopoulos | \ Container ``PUT`` updates metadata/policy. |
64 | 8f9976c6 | Constantinos Venetsanopoulos | \ Report allowed actions in shared object replies. |
65 | 8f9976c6 | Constantinos Venetsanopoulos | \ Provide ``https://hostname/login`` for Shibboleth authentication. |
66 | 8f9976c6 | Constantinos Venetsanopoulos | \ Use ``hashmap`` parameter in object ``GET``/``PUT`` to use hashmaps. |
67 | 8f9976c6 | Constantinos Venetsanopoulos | 0.5 (July 22, 2011) Object update from another object's data. |
68 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support object truncate. |
69 | 8f9976c6 | Constantinos Venetsanopoulos | \ Create object using a standard HTML form. |
70 | 8f9976c6 | Constantinos Venetsanopoulos | \ Purge container/object history. |
71 | 8f9976c6 | Constantinos Venetsanopoulos | \ List other accounts that share objects with a user. |
72 | 8f9976c6 | Constantinos Venetsanopoulos | \ List shared containers/objects. |
73 | 8f9976c6 | Constantinos Venetsanopoulos | \ Update implementation guidelines. |
74 | 8f9976c6 | Constantinos Venetsanopoulos | \ Check preconditions when creating/updating objects. |
75 | 8f9976c6 | Constantinos Venetsanopoulos | 0.4 (July 01, 2011) Object permissions and account groups. |
76 | 8f9976c6 | Constantinos Venetsanopoulos | \ Control versioning behavior and container quotas with container policy directives. |
77 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support updating/deleting individual metadata with ``POST``. |
78 | 8f9976c6 | Constantinos Venetsanopoulos | \ Create object using hashmap. |
79 | 8f9976c6 | Constantinos Venetsanopoulos | 0.3 (June 14, 2011) Large object support with ``X-Object-Manifest``. |
80 | 8f9976c6 | Constantinos Venetsanopoulos | \ Allow for publicly available objects via ``https://hostname/public``. |
81 | 890c2065 | Sofia Papagiannaki | \ Support time-variant account/container listings. |
82 | 8f9976c6 | Constantinos Venetsanopoulos | \ Add source version when duplicating with ``PUT``/``COPY``. |
83 | 8f9976c6 | Constantinos Venetsanopoulos | \ Request version in object ``HEAD``/``GET`` requests (list versions with ``GET``). |
84 | 8f9976c6 | Constantinos Venetsanopoulos | 0.2 (May 31, 2011) Add object meta listing and filtering in containers. |
85 | 8f9976c6 | Constantinos Venetsanopoulos | \ Include underlying storage characteristics in container meta. |
86 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support for partial object updates through ``POST``. |
87 | 8f9976c6 | Constantinos Venetsanopoulos | \ Expose object hashmaps through ``GET``. |
88 | 8f9976c6 | Constantinos Venetsanopoulos | \ Support for multi-range object ``GET`` requests. |
89 | 8f9976c6 | Constantinos Venetsanopoulos | 0.1 (May 17, 2011) Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011). |
90 | 8f9976c6 | Constantinos Venetsanopoulos | ========================= ================================ |
91 | 8f9976c6 | Constantinos Venetsanopoulos | |
92 | dad708b4 | Antony Chazapis | Pithos Users and Authentication |
93 | dad708b4 | Antony Chazapis | ------------------------------- |
94 | 8f9976c6 | Constantinos Venetsanopoulos | |
95 | dad708b4 | Antony Chazapis | In Pithos, each user is uniquely identified by a token. All API requests require a token and each token is internally resolved to an account string. The API uses the account string to identify the user's own files, thus whether a request is local or cross-account. |
96 | 8f9976c6 | Constantinos Venetsanopoulos | |
97 | dad708b4 | Antony Chazapis | Pithos does not keep a user database. For development and testing purposes, user identifiers and their corresponding tokens can be defined in the settings file. However, Pithos is designed with an external authentication service in mind. This service must handle the details of validating user credentials and communicate with Pithos via a middleware software component that, given a token, fills in the internal request account variable. |
98 | 8f9976c6 | Constantinos Venetsanopoulos | |
99 | dad708b4 | Antony Chazapis | Client software using Pithos, if not already knowing a user's identifier and token, should forward to the ``/login`` URI. The Pithos server, depending on its configuration will redirect to the appropriate login page. |
100 | 8f9976c6 | Constantinos Venetsanopoulos | |
101 | 8f9976c6 | Constantinos Venetsanopoulos | The login URI accepts the following parameters: |
102 | 8f9976c6 | Constantinos Venetsanopoulos | |
103 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
104 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
105 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
106 | 8f9976c6 | Constantinos Venetsanopoulos | next The URI to redirect to when the process is finished |
107 | 8f9976c6 | Constantinos Venetsanopoulos | renew Force token renewal (no value parameter) |
108 | 8f9976c6 | Constantinos Venetsanopoulos | force Force logout current user (no value parameter) |
109 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
110 | 8f9976c6 | Constantinos Venetsanopoulos | |
111 | 1c13522f | Sofia Papagiannaki | When done with logging in, the service's login URI should redirect to the URI provided with ``next``, adding the ``token`` parameters which contains authentication token. |
112 | 1c13522f | Sofia Papagiannaki | |
113 | 1c13522f | Sofia Papagiannaki | If ``next`` request parameter is missing the call fails with BadRequest (400) response status. |
114 | 8f9976c6 | Constantinos Venetsanopoulos | |
115 | 8f9976c6 | Constantinos Venetsanopoulos | A user management service that implements a login URI according to these conventions is Astakos (https://code.grnet.gr/projects/astakos), by GRNET. |
116 | 8f9976c6 | Constantinos Venetsanopoulos | |
117 | 890c2065 | Sofia Papagiannaki | User feedback |
118 | 890c2065 | Sofia Papagiannaki | ------------- |
119 | 890c2065 | Sofia Papagiannaki | |
120 | 890c2065 | Sofia Papagiannaki | Client software using Pithos, should forward to the ``/feedback`` URI. The Pithos service, depending on its configuration will delegate the request to the appropriate identity management URI. |
121 | 890c2065 | Sofia Papagiannaki | |
122 | 6848eae1 | Sofia Papagiannaki | ============================ ========= ================== |
123 | 6848eae1 | Sofia Papagiannaki | Uri Method Description |
124 | 6848eae1 | Sofia Papagiannaki | ============================ ========= ================== |
125 | 6848eae1 | Sofia Papagiannaki | ``/pithos/astakos/feedback`` POST Send feedback |
126 | 6848eae1 | Sofia Papagiannaki | ============================ ========= ================== |
127 | dc068945 | Sofia Papagiannaki | |
128 | dc068945 | Sofia Papagiannaki | | |
129 | dc068945 | Sofia Papagiannaki | |
130 | 890c2065 | Sofia Papagiannaki | ====================== ========================= |
131 | 890c2065 | Sofia Papagiannaki | Request Parameter Name Value |
132 | 890c2065 | Sofia Papagiannaki | ====================== ========================= |
133 | 890c2065 | Sofia Papagiannaki | feedback_msg Feedback message |
134 | 890c2065 | Sofia Papagiannaki | feedback_data Additional information about service client status |
135 | 890c2065 | Sofia Papagiannaki | ====================== ========================= |
136 | 890c2065 | Sofia Papagiannaki | |
137 | 890c2065 | Sofia Papagiannaki | | |
138 | 890c2065 | Sofia Papagiannaki | |
139 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
140 | 5d2e61ec | Sofia Papagiannaki | Request Header Name Value |
141 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
142 | 5d2e61ec | Sofia Papagiannaki | X-Auth-Token User authentication token |
143 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
144 | 5d2e61ec | Sofia Papagiannaki | |
145 | 5d2e61ec | Sofia Papagiannaki | | |
146 | 5d2e61ec | Sofia Papagiannaki | |
147 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
148 | 890c2065 | Sofia Papagiannaki | Return Code Description |
149 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
150 | 890c2065 | Sofia Papagiannaki | 200 (OK) The request succeeded |
151 | 890c2065 | Sofia Papagiannaki | 502 (Bad Gateway) Send feedback failure |
152 | 5d2e61ec | Sofia Papagiannaki | 400 (Bad Request) Method not allowed or invalid message data |
153 | 5d2e61ec | Sofia Papagiannaki | 401 (Unauthorized) Missing or expired user token |
154 | 890c2065 | Sofia Papagiannaki | 500 (Internal Server Error) The request cannot be completed because of an internal error |
155 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
156 | 890c2065 | Sofia Papagiannaki | |
157 | 890c2065 | Sofia Papagiannaki | User translation catalogs |
158 | 890c2065 | Sofia Papagiannaki | ------------------------- |
159 | 890c2065 | Sofia Papagiannaki | |
160 | 5d2e61ec | Sofia Papagiannaki | Client software using Pithos, should forward to the ``/user_catalogs`` URI to get uuid to displayname translations and vice versa. The Pithos service, depending on its configuration will delegate the request to the appropriate identity management URI. |
161 | 5d2e61ec | Sofia Papagiannaki | |
162 | 6848eae1 | Sofia Papagiannaki | ================================= ========= ================== |
163 | 6848eae1 | Sofia Papagiannaki | Uri Method Description |
164 | 6848eae1 | Sofia Papagiannaki | ================================= ========= ================== |
165 | 6848eae1 | Sofia Papagiannaki | ``/pithos/astakos/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
166 | 6848eae1 | Sofia Papagiannaki | ================================= ========= ================== |
167 | dc068945 | Sofia Papagiannaki | |
168 | dc068945 | Sofia Papagiannaki | | |
169 | dc068945 | Sofia Papagiannaki | |
170 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
171 | 5d2e61ec | Sofia Papagiannaki | Request Header Name Value |
172 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
173 | 5d2e61ec | Sofia Papagiannaki | X-Auth-Token User authentication token |
174 | 5d2e61ec | Sofia Papagiannaki | ==================== =========================== |
175 | 890c2065 | Sofia Papagiannaki | |
176 | 890c2065 | Sofia Papagiannaki | The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
177 | 890c2065 | Sofia Papagiannaki | |
178 | 890c2065 | Sofia Papagiannaki | Example request content: |
179 | 890c2065 | Sofia Papagiannaki | |
180 | 890c2065 | Sofia Papagiannaki | :: |
181 | 890c2065 | Sofia Papagiannaki | |
182 | 890c2065 | Sofia Papagiannaki | {"displaynames": ["user1@example.com", "user2@example.com"], |
183 | 890c2065 | Sofia Papagiannaki | "uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
184 | 890c2065 | Sofia Papagiannaki | |
185 | 890c2065 | Sofia Papagiannaki | Example reply: |
186 | 890c2065 | Sofia Papagiannaki | |
187 | 890c2065 | Sofia Papagiannaki | :: |
188 | 890c2065 | Sofia Papagiannaki | |
189 | 890c2065 | Sofia Papagiannaki | {"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
190 | 890c2065 | Sofia Papagiannaki | "user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
191 | 890c2065 | Sofia Papagiannaki | 'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
192 | 890c2065 | Sofia Papagiannaki | "ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
193 | 890c2065 | Sofia Papagiannaki | |
194 | 890c2065 | Sofia Papagiannaki | |
195 | 890c2065 | Sofia Papagiannaki | | |
196 | 890c2065 | Sofia Papagiannaki | |
197 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
198 | 890c2065 | Sofia Papagiannaki | Return Code Description |
199 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
200 | 890c2065 | Sofia Papagiannaki | 200 (OK) The request succeeded |
201 | 890c2065 | Sofia Papagiannaki | 400 (Bad Request) Method not allowed or request body is not json formatted |
202 | 5d2e61ec | Sofia Papagiannaki | 401 (Unauthorized) Missing or expired or invalid user token |
203 | 890c2065 | Sofia Papagiannaki | 500 (Internal Server Error) The request cannot be completed because of an internal error |
204 | 890c2065 | Sofia Papagiannaki | =========================== ===================== |
205 | 890c2065 | Sofia Papagiannaki | |
206 | dad708b4 | Antony Chazapis | The Pithos API |
207 | 8f9976c6 | Constantinos Venetsanopoulos | -------------- |
208 | 8f9976c6 | Constantinos Venetsanopoulos | |
209 | dad708b4 | Antony Chazapis | The URI requests supported by the Pithos API follow one of the following forms: |
210 | 8f9976c6 | Constantinos Venetsanopoulos | |
211 | 8f9976c6 | Constantinos Venetsanopoulos | * Top level: ``https://hostname/v1/`` |
212 | 8f9976c6 | Constantinos Venetsanopoulos | * Account level: ``https://hostname/v1/<account>`` |
213 | 8f9976c6 | Constantinos Venetsanopoulos | * Container level: ``https://hostname/v1/<account>/<container>`` |
214 | 8f9976c6 | Constantinos Venetsanopoulos | * Object level: ``https://hostname/v1/<account>/<container>/<object>`` |
215 | 8f9976c6 | Constantinos Venetsanopoulos | |
216 | 8f9976c6 | Constantinos Venetsanopoulos | All requests must include an ``X-Auth-Token`` - as a header, or a parameter. |
217 | 8f9976c6 | Constantinos Venetsanopoulos | |
218 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
219 | 8f9976c6 | Constantinos Venetsanopoulos | |
220 | dfa2d4ba | Sofia Papagiannaki | ============================== ================================ |
221 | dfa2d4ba | Sofia Papagiannaki | Return Code Description |
222 | dfa2d4ba | Sofia Papagiannaki | ============================== ================================ |
223 | dfa2d4ba | Sofia Papagiannaki | 400 (Bad Request) The request is invalid |
224 | dfa2d4ba | Sofia Papagiannaki | 401 (Unauthorized) Missing or invalid token |
225 | dfa2d4ba | Sofia Papagiannaki | 403 (Forbidden) Request not allowed |
226 | dfa2d4ba | Sofia Papagiannaki | 404 (Not Found) The requested resource was not found |
227 | dfa2d4ba | Sofia Papagiannaki | 413 (Request Entity Too Large) Insufficient quota to complete the request |
228 | dfa2d4ba | Sofia Papagiannaki | 503 (Service Unavailable) The request cannot be completed because of an internal error |
229 | dfa2d4ba | Sofia Papagiannaki | ============================== ================================ |
230 | 8f9976c6 | Constantinos Venetsanopoulos | |
231 | 8f9976c6 | Constantinos Venetsanopoulos | Top Level |
232 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^ |
233 | 8f9976c6 | Constantinos Venetsanopoulos | |
234 | 8f9976c6 | Constantinos Venetsanopoulos | List of operations: |
235 | 8f9976c6 | Constantinos Venetsanopoulos | |
236 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
237 | 8f9976c6 | Constantinos Venetsanopoulos | Operation Description |
238 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
239 | 8f9976c6 | Constantinos Venetsanopoulos | GET Authentication (for compatibility with the OOS API) or list allowed accounts |
240 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
241 | 8f9976c6 | Constantinos Venetsanopoulos | |
242 | 8f9976c6 | Constantinos Venetsanopoulos | GET |
243 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
244 | 8f9976c6 | Constantinos Venetsanopoulos | |
245 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
246 | 8f9976c6 | Constantinos Venetsanopoulos | |
247 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
248 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
249 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
250 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded |
251 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
252 | 8f9976c6 | Constantinos Venetsanopoulos | |
253 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
254 | 8f9976c6 | Constantinos Venetsanopoulos | |
255 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
256 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
257 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
258 | 8f9976c6 | Constantinos Venetsanopoulos | limit The amount of results requested (default is 10000) |
259 | 8f9976c6 | Constantinos Venetsanopoulos | marker Return containers with name lexicographically after marker |
260 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional extended reply type (can be ``json`` or ``xml``) |
261 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
262 | 8f9976c6 | Constantinos Venetsanopoulos | |
263 | 8f9976c6 | Constantinos Venetsanopoulos | The reply is a list of account names. |
264 | 8f9976c6 | Constantinos Venetsanopoulos | If a ``format=xml`` or ``format=json`` argument is given, extended information on the accounts will be returned, serialized in the chosen format. |
265 | 8f9976c6 | Constantinos Venetsanopoulos | For each account, the information will include the following (names will be in lower case and with hyphens replaced with underscores): |
266 | 8f9976c6 | Constantinos Venetsanopoulos | |
267 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
268 | 8f9976c6 | Constantinos Venetsanopoulos | Name Description |
269 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
270 | 8f9976c6 | Constantinos Venetsanopoulos | name The name of the account |
271 | 8f9976c6 | Constantinos Venetsanopoulos | last_modified The last account modification date (regardless of ``until``) |
272 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
273 | 8f9976c6 | Constantinos Venetsanopoulos | |
274 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=json`` reply: |
275 | 8f9976c6 | Constantinos Venetsanopoulos | |
276 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
277 | 8f9976c6 | Constantinos Venetsanopoulos | |
278 | 6848eae1 | Sofia Papagiannaki | [{"name": "user-uuid", "last_modified": "2011-12-02T08:10:41.565891+00:00"}, ...] |
279 | 8f9976c6 | Constantinos Venetsanopoulos | |
280 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=xml`` reply: |
281 | 8f9976c6 | Constantinos Venetsanopoulos | |
282 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
283 | 8f9976c6 | Constantinos Venetsanopoulos | |
284 | 8f9976c6 | Constantinos Venetsanopoulos | <?xml version="1.0" encoding="UTF-8"?> |
285 | 8f9976c6 | Constantinos Venetsanopoulos | <accounts> |
286 | 8f9976c6 | Constantinos Venetsanopoulos | <account> |
287 | 6848eae1 | Sofia Papagiannaki | <name>user-uuid</name> |
288 | 8f9976c6 | Constantinos Venetsanopoulos | <last_modified>2011-12-02T08:10:41.565891+00:00</last_modified> |
289 | 8f9976c6 | Constantinos Venetsanopoulos | </account> |
290 | 8f9976c6 | Constantinos Venetsanopoulos | <account>...</account> |
291 | 8f9976c6 | Constantinos Venetsanopoulos | </accounts> |
292 | 8f9976c6 | Constantinos Venetsanopoulos | |
293 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
294 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
295 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
296 | 8f9976c6 | Constantinos Venetsanopoulos | 200 (OK) The request succeeded |
297 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The user has no access to other accounts (only for non-extended replies) |
298 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
299 | 8f9976c6 | Constantinos Venetsanopoulos | |
300 | 8f9976c6 | Constantinos Venetsanopoulos | Will use a ``200`` return code if the reply is of type JSON/XML. |
301 | 8f9976c6 | Constantinos Venetsanopoulos | |
302 | 8f9976c6 | Constantinos Venetsanopoulos | Account Level |
303 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^^^^^ |
304 | 8f9976c6 | Constantinos Venetsanopoulos | |
305 | 8f9976c6 | Constantinos Venetsanopoulos | List of operations: |
306 | 8f9976c6 | Constantinos Venetsanopoulos | |
307 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
308 | 8f9976c6 | Constantinos Venetsanopoulos | Operation Description |
309 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
310 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD Retrieve account metadata |
311 | 8f9976c6 | Constantinos Venetsanopoulos | GET List containers |
312 | 8f9976c6 | Constantinos Venetsanopoulos | POST Update account metadata |
313 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================== |
314 | 8f9976c6 | Constantinos Venetsanopoulos | |
315 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD |
316 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
317 | 8f9976c6 | Constantinos Venetsanopoulos | |
318 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
319 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
320 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
321 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if account has changed since provided timestamp |
322 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if account has not changed since provided timestamp |
323 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
324 | 8f9976c6 | Constantinos Venetsanopoulos | |
325 | 8f9976c6 | Constantinos Venetsanopoulos | | |
326 | 8f9976c6 | Constantinos Venetsanopoulos | |
327 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
328 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
329 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
330 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
331 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
332 | 8f9976c6 | Constantinos Venetsanopoulos | |
333 | 8f9976c6 | Constantinos Venetsanopoulos | Cross-user requests are not allowed to use ``until`` and only include the account modification date in the reply. |
334 | 8f9976c6 | Constantinos Venetsanopoulos | |
335 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ===================== |
336 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
337 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ===================== |
338 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Container-Count The total number of containers |
339 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Bytes-Used The total number of bytes stored |
340 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Until-Timestamp The last account modification date until the timestamp provided |
341 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Group-* Optional user defined groups |
342 | b744fd30 | Sofia Papagiannaki | X-Account-Policy-Quota Account quota limit |
343 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Meta-* Optional user defined metadata |
344 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last account modification date (regardless of ``until``) |
345 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ===================== |
346 | 8f9976c6 | Constantinos Venetsanopoulos | |
347 | 8f9976c6 | Constantinos Venetsanopoulos | | |
348 | 8f9976c6 | Constantinos Venetsanopoulos | |
349 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
350 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
351 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
352 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded |
353 | 8f9976c6 | Constantinos Venetsanopoulos | ================ ===================== |
354 | 8f9976c6 | Constantinos Venetsanopoulos | |
355 | 8f9976c6 | Constantinos Venetsanopoulos | |
356 | 8f9976c6 | Constantinos Venetsanopoulos | GET |
357 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
358 | 8f9976c6 | Constantinos Venetsanopoulos | |
359 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
360 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
361 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
362 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if account has changed since provided timestamp |
363 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if account has not changed since provided timestamp |
364 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
365 | 8f9976c6 | Constantinos Venetsanopoulos | |
366 | 8f9976c6 | Constantinos Venetsanopoulos | | |
367 | 8f9976c6 | Constantinos Venetsanopoulos | |
368 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
369 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
370 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
371 | 8f9976c6 | Constantinos Venetsanopoulos | limit The amount of results requested (default is 10000) |
372 | 8f9976c6 | Constantinos Venetsanopoulos | marker Return containers with name lexicographically after marker |
373 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional extended reply type (can be ``json`` or ``xml``) |
374 | 8f9976c6 | Constantinos Venetsanopoulos | shared Show only shared containers (no value parameter) |
375 | 6fe32fb6 | Sofia Papagiannaki | public Show only public containers (no value parameter / avalaible only for owner requests) |
376 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
377 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ========================= |
378 | 8f9976c6 | Constantinos Venetsanopoulos | |
379 | 8f9976c6 | Constantinos Venetsanopoulos | The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included. |
380 | 8f9976c6 | Constantinos Venetsanopoulos | Cross-user requests are not allowed to use ``until`` and only include the account/container modification dates in the reply. |
381 | 8f9976c6 | Constantinos Venetsanopoulos | |
382 | 8f9976c6 | Constantinos Venetsanopoulos | If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format. |
383 | 8f9976c6 | Constantinos Venetsanopoulos | For each container, the information will include all container metadata, except user-defined (names will be in lower case and with hyphens replaced with underscores): |
384 | 8f9976c6 | Constantinos Venetsanopoulos | |
385 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
386 | 8f9976c6 | Constantinos Venetsanopoulos | Name Description |
387 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
388 | 8f9976c6 | Constantinos Venetsanopoulos | name The name of the container |
389 | 8f9976c6 | Constantinos Venetsanopoulos | count The number of objects inside the container |
390 | 8f9976c6 | Constantinos Venetsanopoulos | bytes The total size of the objects inside the container |
391 | 8f9976c6 | Constantinos Venetsanopoulos | last_modified The last container modification date (regardless of ``until``) |
392 | 8f9976c6 | Constantinos Venetsanopoulos | x_container_until_timestamp The last container modification date until the timestamp provided |
393 | 8f9976c6 | Constantinos Venetsanopoulos | x_container_policy Container behavior and limits |
394 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================ |
395 | 8f9976c6 | Constantinos Venetsanopoulos | |
396 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=json`` reply: |
397 | 8f9976c6 | Constantinos Venetsanopoulos | |
398 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
399 | 8f9976c6 | Constantinos Venetsanopoulos | |
400 | 8f9976c6 | Constantinos Venetsanopoulos | [{"name": "pithos", |
401 | 8f9976c6 | Constantinos Venetsanopoulos | "bytes": 62452, |
402 | 8f9976c6 | Constantinos Venetsanopoulos | "count": 8374, |
403 | 8f9976c6 | Constantinos Venetsanopoulos | "last_modified": "2011-12-02T08:10:41.565891+00:00", |
404 | 8f9976c6 | Constantinos Venetsanopoulos | "x_container_policy": {"quota": "53687091200", "versioning": "auto"}}, ...] |
405 | 8f9976c6 | Constantinos Venetsanopoulos | |
406 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=xml`` reply: |
407 | 8f9976c6 | Constantinos Venetsanopoulos | |
408 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
409 | 8f9976c6 | Constantinos Venetsanopoulos | |
410 | 8f9976c6 | Constantinos Venetsanopoulos | <?xml version="1.0" encoding="UTF-8"?> |
411 | 6848eae1 | Sofia Papagiannaki | <account name="user-uuid"> |
412 | 8f9976c6 | Constantinos Venetsanopoulos | <container> |
413 | 8f9976c6 | Constantinos Venetsanopoulos | <name>pithos</name> |
414 | 8f9976c6 | Constantinos Venetsanopoulos | <bytes>62452</bytes> |
415 | 8f9976c6 | Constantinos Venetsanopoulos | <count>8374</count> |
416 | 8f9976c6 | Constantinos Venetsanopoulos | <last_modified>2011-12-02T08:10:41.565891+00:00</last_modified> |
417 | 8f9976c6 | Constantinos Venetsanopoulos | <x_container_policy> |
418 | 8f9976c6 | Constantinos Venetsanopoulos | <key>quota</key><value>53687091200</value> |
419 | 8f9976c6 | Constantinos Venetsanopoulos | <key>versioning</key><value>auto</value> |
420 | 8f9976c6 | Constantinos Venetsanopoulos | </x_container_policy> |
421 | 8f9976c6 | Constantinos Venetsanopoulos | </container> |
422 | 8f9976c6 | Constantinos Venetsanopoulos | <container>...</container> |
423 | 8f9976c6 | Constantinos Venetsanopoulos | </account> |
424 | 8f9976c6 | Constantinos Venetsanopoulos | |
425 | 8f9976c6 | Constantinos Venetsanopoulos | For more examples of container details returned in JSON/XML formats refer to the OOS API documentation. In addition to the OOS API, Pithos returns policy fields, grouped as key-value pairs. |
426 | 8f9976c6 | Constantinos Venetsanopoulos | |
427 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
428 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
429 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
430 | 8f9976c6 | Constantinos Venetsanopoulos | 200 (OK) The request succeeded |
431 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The account has no containers (only for non-extended replies) |
432 | 8f9976c6 | Constantinos Venetsanopoulos | 304 (Not Modified) The account has not been modified |
433 | c8860319 | Sofia Papagiannaki | 403 (Forbidden) Public is requested but the request user is not the path owner |
434 | 8f9976c6 | Constantinos Venetsanopoulos | 412 (Precondition Failed) The condition set can not be satisfied |
435 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ===================== |
436 | 8f9976c6 | Constantinos Venetsanopoulos | |
437 | 8f9976c6 | Constantinos Venetsanopoulos | Will use a ``200`` return code if the reply is of type JSON/XML. |
438 | 8f9976c6 | Constantinos Venetsanopoulos | |
439 | 8f9976c6 | Constantinos Venetsanopoulos | |
440 | 8f9976c6 | Constantinos Venetsanopoulos | POST |
441 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
442 | 8f9976c6 | Constantinos Venetsanopoulos | |
443 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
444 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
445 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
446 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Group-* Optional user defined groups |
447 | 8f9976c6 | Constantinos Venetsanopoulos | X-Account-Meta-* Optional user defined metadata |
448 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
449 | 8f9976c6 | Constantinos Venetsanopoulos | |
450 | 8f9976c6 | Constantinos Venetsanopoulos | | |
451 | 8f9976c6 | Constantinos Venetsanopoulos | |
452 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
453 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
454 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
455 | 8f9976c6 | Constantinos Venetsanopoulos | update Do not replace metadata/groups (no value parameter) |
456 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
457 | 8f9976c6 | Constantinos Venetsanopoulos | |
458 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content/headers. |
459 | 8f9976c6 | Constantinos Venetsanopoulos | |
460 | 8f9976c6 | Constantinos Venetsanopoulos | The operation will overwrite all user defined metadata, except if ``update`` is defined. |
461 | ff827ed3 | Sofia Papagiannaki | To create a group, include an ``X-Account-Group-*`` header with the name in the key and a comma separated list of user identifiers 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. |
462 | 8f9976c6 | Constantinos Venetsanopoulos | |
463 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
464 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
465 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
466 | 8f9976c6 | Constantinos Venetsanopoulos | 202 (Accepted) The request has been accepted |
467 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
468 | 8f9976c6 | Constantinos Venetsanopoulos | |
469 | 8f9976c6 | Constantinos Venetsanopoulos | |
470 | 8f9976c6 | Constantinos Venetsanopoulos | Container Level |
471 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^^^^^^^ |
472 | 8f9976c6 | Constantinos Venetsanopoulos | |
473 | 8f9976c6 | Constantinos Venetsanopoulos | List of operations: |
474 | 8f9976c6 | Constantinos Venetsanopoulos | |
475 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ============================ |
476 | 8f9976c6 | Constantinos Venetsanopoulos | Operation Description |
477 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ============================ |
478 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD Retrieve container metadata |
479 | 8f9976c6 | Constantinos Venetsanopoulos | GET List objects |
480 | 8f9976c6 | Constantinos Venetsanopoulos | PUT Create/update container |
481 | 8f9976c6 | Constantinos Venetsanopoulos | POST Update container metadata |
482 | 8f9976c6 | Constantinos Venetsanopoulos | DELETE Delete container |
483 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ============================ |
484 | 8f9976c6 | Constantinos Venetsanopoulos | |
485 | 8f9976c6 | Constantinos Venetsanopoulos | |
486 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD |
487 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
488 | 8f9976c6 | Constantinos Venetsanopoulos | |
489 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
490 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
491 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
492 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if container has changed since provided timestamp |
493 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if container has not changed since provided timestamp |
494 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
495 | 8f9976c6 | Constantinos Venetsanopoulos | |
496 | 8f9976c6 | Constantinos Venetsanopoulos | | |
497 | 8f9976c6 | Constantinos Venetsanopoulos | |
498 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
499 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
500 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
501 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
502 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
503 | 8f9976c6 | Constantinos Venetsanopoulos | |
504 | 8f9976c6 | Constantinos Venetsanopoulos | Cross-user requests are not allowed to use ``until`` and only include the container modification date in the reply. |
505 | 8f9976c6 | Constantinos Venetsanopoulos | |
506 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
507 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
508 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
509 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Object-Count The total number of objects in the container |
510 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Bytes-Used The total number of bytes of all objects stored |
511 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Block-Size The block size used by the storage backend |
512 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps |
513 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Until-Timestamp The last container modification date until the timestamp provided |
514 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Object-Meta A list with all meta keys used by objects (**TBD**) |
515 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Policy-* Container behavior and limits |
516 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Meta-* Optional user defined metadata |
517 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last container modification date (regardless of ``until``) |
518 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
519 | 8f9976c6 | Constantinos Venetsanopoulos | |
520 | 8f9976c6 | Constantinos Venetsanopoulos | 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. (**TBD**) |
521 | 8f9976c6 | Constantinos Venetsanopoulos | |
522 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
523 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
524 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
525 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded |
526 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
527 | 8f9976c6 | Constantinos Venetsanopoulos | |
528 | 8f9976c6 | Constantinos Venetsanopoulos | |
529 | 8f9976c6 | Constantinos Venetsanopoulos | GET |
530 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
531 | 8f9976c6 | Constantinos Venetsanopoulos | |
532 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
533 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
534 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
535 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if container has changed since provided timestamp |
536 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if container has not changed since provided timestamp |
537 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== =========================== |
538 | 8f9976c6 | Constantinos Venetsanopoulos | |
539 | 8f9976c6 | Constantinos Venetsanopoulos | | |
540 | 8f9976c6 | Constantinos Venetsanopoulos | |
541 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
542 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
543 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
544 | 8f9976c6 | Constantinos Venetsanopoulos | limit The amount of results requested (default is 10000) |
545 | 8f9976c6 | Constantinos Venetsanopoulos | marker Return containers with name lexicographically after marker |
546 | 8f9976c6 | Constantinos Venetsanopoulos | prefix Return objects starting with prefix |
547 | 8f9976c6 | Constantinos Venetsanopoulos | delimiter Return objects up to the delimiter (discussion follows) |
548 | 8f9976c6 | Constantinos Venetsanopoulos | path Assume ``prefix=path`` and ``delimiter=/`` |
549 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional extended reply type (can be ``json`` or ``xml``) |
550 | 8f9976c6 | Constantinos Venetsanopoulos | meta Return objects that satisfy the key queries in the specified comma separated list (use ``<key>``, ``!<key>`` for existence queries, ``<key><op><value>`` for value queries, where ``<op>`` can be one of ``=``, ``!=``, ``<=``, ``>=``, ``<``, ``>``) |
551 | 6fe32fb6 | Sofia Papagiannaki | shared Show only objects (no value parameter) |
552 | c8860319 | Sofia Papagiannaki | public Show only public objects (no value parameter / avalaible only for owner requests) |
553 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
554 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
555 | 8f9976c6 | Constantinos Venetsanopoulos | |
556 | 8f9976c6 | Constantinos Venetsanopoulos | The ``path`` parameter overrides ``prefix`` and ``delimiter``. When using ``path``, results will include objects ending in ``delimiter``. |
557 | 8f9976c6 | Constantinos Venetsanopoulos | |
558 | 8f9976c6 | Constantinos Venetsanopoulos | The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix. |
559 | 8f9976c6 | Constantinos Venetsanopoulos | |
560 | 8f9976c6 | Constantinos Venetsanopoulos | The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included. |
561 | 8f9976c6 | Constantinos Venetsanopoulos | Cross-user requests are not allowed to use ``until`` and include the following limited set of headers in the reply: |
562 | 8f9976c6 | Constantinos Venetsanopoulos | |
563 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
564 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
565 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
566 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Block-Size The block size used by the storage backend |
567 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps |
568 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Object-Meta A list with all meta keys used by allowed objects (**TBD**) |
569 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last container modification date |
570 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
571 | 8f9976c6 | Constantinos Venetsanopoulos | |
572 | 8f9976c6 | Constantinos Venetsanopoulos | If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format. |
573 | 8f9976c6 | Constantinos Venetsanopoulos | For each object, the information will include all object metadata, except user-defined (names will be in lower case and with hyphens replaced with underscores). User-defined metadata includes ``X-Object-Meta-*``, ``X-Object-Manifest``, ``Content-Disposition`` and ``Content-Encoding`` keys. Also, sharing directives will only be included with the actual shared objects (inherited permissions are not calculated): |
574 | 8f9976c6 | Constantinos Venetsanopoulos | |
575 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ====================================== |
576 | 8f9976c6 | Constantinos Venetsanopoulos | Name Description |
577 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ====================================== |
578 | 8f9976c6 | Constantinos Venetsanopoulos | name The name of the object |
579 | 8f9976c6 | Constantinos Venetsanopoulos | hash The ETag of the object |
580 | 8f9976c6 | Constantinos Venetsanopoulos | bytes The size of the object |
581 | 8f9976c6 | Constantinos Venetsanopoulos | content_type The MIME content type of the object |
582 | 8f9976c6 | Constantinos Venetsanopoulos | last_modified The last object modification date (regardless of version) |
583 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_hash The Merkle hash |
584 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_uuid The object's UUID |
585 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_version The object's version identifier |
586 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_version_timestamp The object's version timestamp |
587 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_modified_by The user that committed the object's version |
588 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_sharing Object permissions (optional) |
589 | 8f9976c6 | Constantinos Venetsanopoulos | x_object_allowed_to Allowed actions on object (optional) |
590 | 1a3eff62 | Sofia Papagiannaki | x_object_public Object's publicly accessible URI (optional: present if the object is public and the request user is the object owner) |
591 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== ====================================== |
592 | 8f9976c6 | Constantinos Venetsanopoulos | |
593 | 8f9976c6 | Constantinos Venetsanopoulos | Sharing metadata and last modification timestamp will only be returned if there is no ``until`` parameter defined. |
594 | 8f9976c6 | Constantinos Venetsanopoulos | |
595 | 8f9976c6 | Constantinos Venetsanopoulos | Extended replies may also include virtual directory markers in separate sections of the ``json`` or ``xml`` results. |
596 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
597 | 8f9976c6 | Constantinos Venetsanopoulos | In JSON results they appear as dictionaries with only a ``subdir`` key. In XML results they appear interleaved with ``<object>`` tags as ``<subdir name="..." />``. |
598 | 8f9976c6 | Constantinos Venetsanopoulos | In case there is an object with the same name as a virtual directory marker, the object will be returned. |
599 | 8f9976c6 | Constantinos Venetsanopoulos | |
600 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=json`` reply: |
601 | 8f9976c6 | Constantinos Venetsanopoulos | |
602 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
603 | 8f9976c6 | Constantinos Venetsanopoulos | |
604 | 8f9976c6 | Constantinos Venetsanopoulos | [{"name": "object", |
605 | 8f9976c6 | Constantinos Venetsanopoulos | "bytes": 0, |
606 | 8f9976c6 | Constantinos Venetsanopoulos | "hash": "d41d8cd98f00b204e9800998ecf8427e", |
607 | 8f9976c6 | Constantinos Venetsanopoulos | "content_type": "application/octet-stream", |
608 | 8f9976c6 | Constantinos Venetsanopoulos | "last_modified": "2011-12-02T08:10:41.565891+00:00", |
609 | 8f9976c6 | Constantinos Venetsanopoulos | "x_object_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", |
610 | 8f9976c6 | Constantinos Venetsanopoulos | "x_object_uuid": "8ed9af1b-c948-4bb6-82b0-48344f5c822c", |
611 | 8f9976c6 | Constantinos Venetsanopoulos | "x_object_version": 98, |
612 | 8f9976c6 | Constantinos Venetsanopoulos | "x_object_version_timestamp": "1322813441.565891", |
613 | 6848eae1 | Sofia Papagiannaki | "x_object_modified_by": "user-uuid"}, ...] |
614 | 8f9976c6 | Constantinos Venetsanopoulos | |
615 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=xml`` reply: |
616 | 8f9976c6 | Constantinos Venetsanopoulos | |
617 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
618 | 8f9976c6 | Constantinos Venetsanopoulos | |
619 | 8f9976c6 | Constantinos Venetsanopoulos | <?xml version="1.0" encoding="UTF-8"?> |
620 | 8f9976c6 | Constantinos Venetsanopoulos | <container name="pithos"> |
621 | 8f9976c6 | Constantinos Venetsanopoulos | <object> |
622 | 8f9976c6 | Constantinos Venetsanopoulos | <name>object</name> |
623 | 8f9976c6 | Constantinos Venetsanopoulos | <bytes>0</bytes> |
624 | 8f9976c6 | Constantinos Venetsanopoulos | <hash>d41d8cd98f00b204e9800998ecf8427e</hash> |
625 | 8f9976c6 | Constantinos Venetsanopoulos | <content_type>application/octet-stream</content_type> |
626 | 8f9976c6 | Constantinos Venetsanopoulos | <last_modified>2011-12-02T08:10:41.565891+00:00</last_modified> |
627 | 8f9976c6 | Constantinos Venetsanopoulos | <x_object_hash>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</x_object_hash> |
628 | 8f9976c6 | Constantinos Venetsanopoulos | <x_object_uuid>8ed9af1b-c948-4bb6-82b0-48344f5c822c</x_object_uuid> |
629 | 8f9976c6 | Constantinos Venetsanopoulos | <x_object_version>98</x_object_version> |
630 | 8f9976c6 | Constantinos Venetsanopoulos | <x_object_version_timestamp>1322813441.565891</x_object_version_timestamp> |
631 | 6848eae1 | Sofia Papagiannaki | <x_object_modified_by>user-uuid</x_object_modified_by> |
632 | 8f9976c6 | Constantinos Venetsanopoulos | </object> |
633 | 8f9976c6 | Constantinos Venetsanopoulos | <object>...</object> |
634 | 8f9976c6 | Constantinos Venetsanopoulos | </container> |
635 | 8f9976c6 | Constantinos Venetsanopoulos | |
636 | 8f9976c6 | Constantinos Venetsanopoulos | For more examples of container details returned in JSON/XML formats refer to the OOS API documentation. In addition to the OOS API, Pithos returns more fields that should help with synchronization. |
637 | 8f9976c6 | Constantinos Venetsanopoulos | |
638 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
639 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
640 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
641 | 8f9976c6 | Constantinos Venetsanopoulos | 200 (OK) The request succeeded |
642 | ec9e2641 | Sofia Papagiannaki | 204 (No Content) The container has no objects (only for non-extended replies) |
643 | 8f9976c6 | Constantinos Venetsanopoulos | 304 (Not Modified) The container has not been modified |
644 | c8860319 | Sofia Papagiannaki | 403 (Forbidden) Public is requested but the request user is not the path owner |
645 | 8f9976c6 | Constantinos Venetsanopoulos | 412 (Precondition Failed) The condition set can not be satisfied |
646 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== =============================== |
647 | 8f9976c6 | Constantinos Venetsanopoulos | |
648 | 8f9976c6 | Constantinos Venetsanopoulos | Will use a ``200`` return code if the reply is of type JSON/XML. |
649 | 8f9976c6 | Constantinos Venetsanopoulos | |
650 | 8f9976c6 | Constantinos Venetsanopoulos | |
651 | 8f9976c6 | Constantinos Venetsanopoulos | PUT |
652 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
653 | 8f9976c6 | Constantinos Venetsanopoulos | |
654 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
655 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
656 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
657 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Policy-* Container behavior and limits |
658 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Meta-* Optional user defined metadata |
659 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
660 | 8f9976c6 | Constantinos Venetsanopoulos | |
661 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content/headers. |
662 | 8f9976c6 | Constantinos Venetsanopoulos | |
663 | 8f9976c6 | Constantinos Venetsanopoulos | If no policy is defined, the container will be created with the default values. |
664 | 8f9976c6 | Constantinos Venetsanopoulos | Available policy directives: |
665 | 8f9976c6 | Constantinos Venetsanopoulos | |
666 | 8f9976c6 | Constantinos Venetsanopoulos | * ``versioning``: Set to ``auto`` or ``none`` (default is ``auto``) |
667 | 8f9976c6 | Constantinos Venetsanopoulos | * ``quota``: Size limit in KB (default is ``0`` - unlimited) |
668 | 8f9976c6 | Constantinos Venetsanopoulos | |
669 | 8f9976c6 | Constantinos Venetsanopoulos | If the container already exists, the operation is equal to a ``POST`` with ``update`` defined. |
670 | 8f9976c6 | Constantinos Venetsanopoulos | |
671 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
672 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
673 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
674 | 8f9976c6 | Constantinos Venetsanopoulos | 201 (Created) The container has been created |
675 | 8f9976c6 | Constantinos Venetsanopoulos | 202 (Accepted) The request has been accepted |
676 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
677 | 8f9976c6 | Constantinos Venetsanopoulos | |
678 | 8f9976c6 | Constantinos Venetsanopoulos | |
679 | 8f9976c6 | Constantinos Venetsanopoulos | POST |
680 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
681 | 8f9976c6 | Constantinos Venetsanopoulos | |
682 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
683 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
684 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
685 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the supplied data (optional, to upload) |
686 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the supplied data (optional, to upload) |
687 | 8f9976c6 | Constantinos Venetsanopoulos | Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored) |
688 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Policy-* Container behavior and limits |
689 | 8f9976c6 | Constantinos Venetsanopoulos | X-Container-Meta-* Optional user defined metadata |
690 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
691 | 8f9976c6 | Constantinos Venetsanopoulos | |
692 | 8f9976c6 | Constantinos Venetsanopoulos | | |
693 | 8f9976c6 | Constantinos Venetsanopoulos | |
694 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
695 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
696 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
697 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional hash list reply type (can be ``json`` or ``xml``) |
698 | 8f9976c6 | Constantinos Venetsanopoulos | update Do not replace metadata/policy (no value parameter) |
699 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
700 | 8f9976c6 | Constantinos Venetsanopoulos | |
701 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content/headers, except when uploading data, where the reply consists of a list of hashes for the blocks received (in the format specified). |
702 | 8f9976c6 | Constantinos Venetsanopoulos | |
703 | 8f9976c6 | Constantinos Venetsanopoulos | The operation will overwrite all user defined metadata, except if ``update`` is defined. |
704 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
705 | 8f9976c6 | Constantinos Venetsanopoulos | |
706 | 8f9976c6 | Constantinos Venetsanopoulos | To upload blocks of data to the container, set ``Content-Type`` to ``application/octet-stream`` and ``Content-Length`` to a valid value (except if using ``chunked`` as the ``Transfer-Encoding``). |
707 | 8f9976c6 | Constantinos Venetsanopoulos | |
708 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
709 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
710 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
711 | 8f9976c6 | Constantinos Venetsanopoulos | 202 (Accepted) The request has been accepted |
712 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
713 | 8f9976c6 | Constantinos Venetsanopoulos | |
714 | 8f9976c6 | Constantinos Venetsanopoulos | |
715 | 8f9976c6 | Constantinos Venetsanopoulos | DELETE |
716 | 8f9976c6 | Constantinos Venetsanopoulos | """""" |
717 | 8f9976c6 | Constantinos Venetsanopoulos | |
718 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
719 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
720 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
721 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
722 | 87a157c1 | Sofia Papagiannaki | delimiter Optional delete objects starting with container name and delimiter |
723 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
724 | 8f9976c6 | Constantinos Venetsanopoulos | |
725 | 87a157c1 | Sofia Papagiannaki | If ``until`` is defined, the container is "purged" up to that time (the history of all objects up to then is deleted). If also ``delimiter`` is defined, purge is applied only on the container. |
726 | 8f9976c6 | Constantinos Venetsanopoulos | |
727 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content/headers. |
728 | 8f9976c6 | Constantinos Venetsanopoulos | |
729 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
730 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
731 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
732 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded |
733 | 8f9976c6 | Constantinos Venetsanopoulos | 409 (Conflict) The container is not empty |
734 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
735 | 8f9976c6 | Constantinos Venetsanopoulos | |
736 | 8f9976c6 | Constantinos Venetsanopoulos | |
737 | 8f9976c6 | Constantinos Venetsanopoulos | Object Level |
738 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^^^^ |
739 | 8f9976c6 | Constantinos Venetsanopoulos | |
740 | 8f9976c6 | Constantinos Venetsanopoulos | List of operations: |
741 | 8f9976c6 | Constantinos Venetsanopoulos | |
742 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================================= |
743 | 8f9976c6 | Constantinos Venetsanopoulos | Operation Description |
744 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================================= |
745 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD Retrieve object metadata |
746 | 8f9976c6 | Constantinos Venetsanopoulos | GET Read object data |
747 | 8f9976c6 | Constantinos Venetsanopoulos | PUT Write object data or copy/move object |
748 | 8f9976c6 | Constantinos Venetsanopoulos | COPY Copy object |
749 | 8f9976c6 | Constantinos Venetsanopoulos | MOVE Move object |
750 | 8f9976c6 | Constantinos Venetsanopoulos | POST Update object metadata/data |
751 | 8f9976c6 | Constantinos Venetsanopoulos | DELETE Delete object |
752 | 8f9976c6 | Constantinos Venetsanopoulos | ========= ================================= |
753 | 8f9976c6 | Constantinos Venetsanopoulos | |
754 | 8f9976c6 | Constantinos Venetsanopoulos | |
755 | 8f9976c6 | Constantinos Venetsanopoulos | HEAD |
756 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
757 | 8f9976c6 | Constantinos Venetsanopoulos | |
758 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
759 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
760 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
761 | 8f9976c6 | Constantinos Venetsanopoulos | If-Match Retrieve if ETags match |
762 | 8f9976c6 | Constantinos Venetsanopoulos | If-None-Match Retrieve if ETags don't match |
763 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if object has changed since provided timestamp |
764 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if object has not changed since provided timestamp |
765 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
766 | 8f9976c6 | Constantinos Venetsanopoulos | |
767 | 8f9976c6 | Constantinos Venetsanopoulos | | |
768 | 8f9976c6 | Constantinos Venetsanopoulos | |
769 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
770 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
771 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
772 | 8f9976c6 | Constantinos Venetsanopoulos | version Optional version identifier |
773 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
774 | 8f9976c6 | Constantinos Venetsanopoulos | |
775 | 8f9976c6 | Constantinos Venetsanopoulos | | |
776 | 8f9976c6 | Constantinos Venetsanopoulos | |
777 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
778 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
779 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
780 | 8f9976c6 | Constantinos Venetsanopoulos | ETag The ETag of the object |
781 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the object |
782 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object |
783 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last object modification date (regardless of version) |
784 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
785 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
786 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Hash The Merkle hash |
787 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-UUID The object's UUID |
788 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's version identifier |
789 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version-Timestamp The object's version timestamp |
790 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Modified-By The user that comitted the object's version |
791 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
792 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Sharing Object permissions (optional) |
793 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Shared-By Object inheriting permissions (optional) |
794 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Allowed-To Allowed actions on object (optional) |
795 | 1a3eff62 | Sofia Papagiannaki | X-Object-Public Object's publicly accessible URI (optional: present if the object is public and the request user is the object owner) |
796 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Meta-* Optional user defined metadata |
797 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
798 | 8f9976c6 | Constantinos Venetsanopoulos | |
799 | 8f9976c6 | Constantinos Venetsanopoulos | | |
800 | 8f9976c6 | Constantinos Venetsanopoulos | |
801 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
802 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
803 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
804 | 8f9976c6 | Constantinos Venetsanopoulos | 200 (No Content) The request succeeded |
805 | 8f9976c6 | Constantinos Venetsanopoulos | ================ =============================== |
806 | 8f9976c6 | Constantinos Venetsanopoulos | |
807 | 8f9976c6 | Constantinos Venetsanopoulos | |
808 | 8f9976c6 | Constantinos Venetsanopoulos | GET |
809 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
810 | 8f9976c6 | Constantinos Venetsanopoulos | |
811 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
812 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
813 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
814 | 8f9976c6 | Constantinos Venetsanopoulos | Range Optional range of data to retrieve |
815 | 8f9976c6 | Constantinos Venetsanopoulos | If-Range Retrieve the missing part if entity is unchanged; otherwise, retrieve the entire new entity (used together with Range header) |
816 | 8f9976c6 | Constantinos Venetsanopoulos | If-Match Retrieve if ETags match |
817 | 8f9976c6 | Constantinos Venetsanopoulos | If-None-Match Retrieve if ETags don't match |
818 | 8f9976c6 | Constantinos Venetsanopoulos | If-Modified-Since Retrieve if object has changed since provided timestamp |
819 | 8f9976c6 | Constantinos Venetsanopoulos | If-Unmodified-Since Retrieve if object has not changed since provided timestamp |
820 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
821 | 8f9976c6 | Constantinos Venetsanopoulos | |
822 | 8f9976c6 | Constantinos Venetsanopoulos | | |
823 | 8f9976c6 | Constantinos Venetsanopoulos | |
824 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
825 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
826 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
827 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional extended reply type (can be ``json`` or ``xml``) |
828 | 8f9976c6 | Constantinos Venetsanopoulos | hashmap Optional request for hashmap (no value parameter) |
829 | 8f9976c6 | Constantinos Venetsanopoulos | version Optional version identifier or ``list`` (specify a format if requesting a list) |
830 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
831 | 8f9976c6 | Constantinos Venetsanopoulos | |
832 | 8f9976c6 | Constantinos Venetsanopoulos | The reply is the object's data (or part of it), except if a hashmap is requested with ``hashmap``, or a version list with ``version=list`` (in both cases an extended reply format must be specified). Object headers (as in a ``HEAD`` request) are always included. |
833 | 8f9976c6 | Constantinos Venetsanopoulos | |
834 | 8f9976c6 | Constantinos Venetsanopoulos | Hashmaps expose the underlying storage format of the object. Note that each hash is computed after trimming trailing null bytes of the corresponding block. The ``X-Object-Hash`` header reports the single Merkle hash of the object's hashmap (refer to http://bittorrent.org/beps/bep_0030.html for more information). |
835 | 8f9976c6 | Constantinos Venetsanopoulos | |
836 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=json`` reply: |
837 | 8f9976c6 | Constantinos Venetsanopoulos | |
838 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
839 | 8f9976c6 | Constantinos Venetsanopoulos | |
840 | 8f9976c6 | Constantinos Venetsanopoulos | {"block_hash": "sha1", "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...], "block_size": 131072, "bytes": 242} |
841 | 8f9976c6 | Constantinos Venetsanopoulos | |
842 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=xml`` reply: |
843 | 8f9976c6 | Constantinos Venetsanopoulos | |
844 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
845 | 8f9976c6 | Constantinos Venetsanopoulos | |
846 | 8f9976c6 | Constantinos Venetsanopoulos | <?xml version="1.0" encoding="UTF-8"?> |
847 | 8f9976c6 | Constantinos Venetsanopoulos | <object name="file" bytes="24223726" block_size="131072" block_hash="sha1"> |
848 | 8f9976c6 | Constantinos Venetsanopoulos | <hash>7295c41da03d7f916440b98e32c4a2a39351546c</hash> |
849 | 8f9976c6 | Constantinos Venetsanopoulos | <hash>...</hash> |
850 | 8f9976c6 | Constantinos Venetsanopoulos | </object> |
851 | 8f9976c6 | Constantinos Venetsanopoulos | |
852 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
853 | 8f9976c6 | Constantinos Venetsanopoulos | |
854 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=json`` reply: |
855 | 8f9976c6 | Constantinos Venetsanopoulos | |
856 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
857 | 8f9976c6 | Constantinos Venetsanopoulos | |
858 | 8f9976c6 | Constantinos Venetsanopoulos | {"versions": [[85, "1322734861.248469"], [86, "1322734905.009272"], ...]} |
859 | 8f9976c6 | Constantinos Venetsanopoulos | |
860 | 8f9976c6 | Constantinos Venetsanopoulos | Example ``format=xml`` reply: |
861 | 8f9976c6 | Constantinos Venetsanopoulos | |
862 | 8f9976c6 | Constantinos Venetsanopoulos | :: |
863 | 8f9976c6 | Constantinos Venetsanopoulos | |
864 | 8f9976c6 | Constantinos Venetsanopoulos | <?xml version="1.0" encoding="UTF-8"?> |
865 | 8f9976c6 | Constantinos Venetsanopoulos | <object name="file"> |
866 | 8f9976c6 | Constantinos Venetsanopoulos | <version timestamp="1322734861.248469">85</version> |
867 | 8f9976c6 | Constantinos Venetsanopoulos | <version timestamp="1322734905.009272">86</version> |
868 | 8f9976c6 | Constantinos Venetsanopoulos | <version timestamp="...">...</version> |
869 | 8f9976c6 | Constantinos Venetsanopoulos | </object> |
870 | 8f9976c6 | Constantinos Venetsanopoulos | |
871 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
872 | 8f9976c6 | Constantinos Venetsanopoulos | |
873 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
874 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
875 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
876 | 8f9976c6 | Constantinos Venetsanopoulos | ETag The ETag of the object |
877 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the data returned |
878 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object |
879 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Range The range of data included (only on a single range request) |
880 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last object modification date (regardless of version) |
881 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
882 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
883 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Hash The Merkle hash |
884 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-UUID The object's UUID |
885 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's version identifier |
886 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version-Timestamp The object's version timestamp |
887 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Modified-By The user that comitted the object's version |
888 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
889 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Sharing Object permissions (optional) |
890 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Shared-By Object inheriting permissions (optional) |
891 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Allowed-To Allowed actions on object (optional) |
892 | 1a3eff62 | Sofia Papagiannaki | X-Object-Public Object's publicly accessible URI (optional: present if the object is public and the request user is the object owner) |
893 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Meta-* Optional user defined metadata |
894 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
895 | 8f9976c6 | Constantinos Venetsanopoulos | |
896 | 8f9976c6 | Constantinos Venetsanopoulos | Sharing headers (``X-Object-Sharing``, ``X-Object-Shared-By`` and ``X-Object-Allowed-To``) are only included if the request is for the object's latest version (no specific ``version`` parameter is set). |
897 | 8f9976c6 | Constantinos Venetsanopoulos | |
898 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
899 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
900 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
901 | 8f9976c6 | Constantinos Venetsanopoulos | 200 (OK) The request succeeded |
902 | 8f9976c6 | Constantinos Venetsanopoulos | 206 (Partial Content) The range request succeeded |
903 | 8f9976c6 | Constantinos Venetsanopoulos | 304 (Not Modified) The object has not been modified |
904 | 8f9976c6 | Constantinos Venetsanopoulos | 412 (Precondition Failed) The condition set can not be satisfied |
905 | 8f9976c6 | Constantinos Venetsanopoulos | 416 (Range Not Satisfiable) The requested range is out of limits |
906 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
907 | 8f9976c6 | Constantinos Venetsanopoulos | |
908 | 8f9976c6 | Constantinos Venetsanopoulos | |
909 | 8f9976c6 | Constantinos Venetsanopoulos | PUT |
910 | 8f9976c6 | Constantinos Venetsanopoulos | """ |
911 | 8f9976c6 | Constantinos Venetsanopoulos | |
912 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
913 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
914 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
915 | 8f9976c6 | Constantinos Venetsanopoulos | If-Match Put if ETags match with current object |
916 | 8f9976c6 | Constantinos Venetsanopoulos | If-None-Match Put if ETags don't match with current object |
917 | 8f9976c6 | Constantinos Venetsanopoulos | ETag The MD5 hash of the object (optional to check written data) |
918 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the data written |
919 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object |
920 | 8f9976c6 | Constantinos Venetsanopoulos | Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored) |
921 | 8f9976c6 | Constantinos Venetsanopoulos | X-Copy-From The source path in the form ``/<container>/<object>`` |
922 | 8f9976c6 | Constantinos Venetsanopoulos | X-Move-From The source path in the form ``/<container>/<object>`` |
923 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Account The source account to copy/move from |
924 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Version The source version to copy from |
925 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
926 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
927 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
928 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Sharing Object permissions (optional) |
929 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Public Object is publicly accessible (optional) |
930 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Meta-* Optional user defined metadata |
931 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
932 | 8f9976c6 | Constantinos Venetsanopoulos | |
933 | 8f9976c6 | Constantinos Venetsanopoulos | | |
934 | 8f9976c6 | Constantinos Venetsanopoulos | |
935 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
936 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
937 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
938 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional extended request/conflict response type (can be ``json`` or ``xml``) |
939 | 8f9976c6 | Constantinos Venetsanopoulos | hashmap Optional hashmap provided instead of data (no value parameter) |
940 | 87a157c1 | Sofia Papagiannaki | delimiter Optional copy/move objects starting with object's path and delimiter (to be used with X-Copy-From/X-Move-From) |
941 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
942 | 8f9976c6 | Constantinos Venetsanopoulos | |
943 | 8f9976c6 | Constantinos Venetsanopoulos | The request is the object's data (or part of it), except if a hashmap is provided (using ``hashmap`` and ``format`` parameters). If using a hashmap 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 (in simple text format, with one hash per line, or in JSON/XML - depending on the ``format`` parameter). |
944 | 8f9976c6 | Constantinos Venetsanopoulos | |
945 | 8f9976c6 | Constantinos Venetsanopoulos | Hashmaps should be formatted as outlined in ``GET``. |
946 | 8f9976c6 | Constantinos Venetsanopoulos | |
947 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
948 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
949 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
950 | 133e3fcf | Sofia Papagiannaki | ETag The MD5 (or the Merkle if MD5 is deactivated) hash of the object |
951 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's new version |
952 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
953 | 8f9976c6 | Constantinos Venetsanopoulos | |
954 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
955 | 8f9976c6 | Constantinos Venetsanopoulos | |
956 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
957 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
958 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
959 | 8f9976c6 | Constantinos Venetsanopoulos | 201 (Created) The object has been created |
960 | 8f9976c6 | Constantinos Venetsanopoulos | 409 (Conflict) The object can not be created from the provided hashmap (a list of missing hashes will be included in the reply) |
961 | 8f9976c6 | Constantinos Venetsanopoulos | 411 (Length Required) Missing ``Content-Length`` or ``Content-Type`` in the request |
962 | 8f9976c6 | Constantinos Venetsanopoulos | 413 (Request Entity Too Large) Insufficient quota to complete the request |
963 | 133e3fcf | Sofia Papagiannaki | 422 (Unprocessable Entity) The MD5 (or the Merkle if MD5 is deactivated) checksum of the data written to the storage system does not match the (optionally) supplied ETag value |
964 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
965 | 8f9976c6 | Constantinos Venetsanopoulos | |
966 | 8f9976c6 | Constantinos Venetsanopoulos | |
967 | 8f9976c6 | Constantinos Venetsanopoulos | COPY |
968 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
969 | 8f9976c6 | Constantinos Venetsanopoulos | |
970 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
971 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
972 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
973 | 8f9976c6 | Constantinos Venetsanopoulos | If-Match Proceed if ETags match with object |
974 | 8f9976c6 | Constantinos Venetsanopoulos | If-None-Match Proceed if ETags don't match with object |
975 | 8f9976c6 | Constantinos Venetsanopoulos | Destination The destination path in the form ``/<container>/<object>`` |
976 | 8f9976c6 | Constantinos Venetsanopoulos | Destination-Account The destination account to copy to |
977 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object (optional :sup:`*`) |
978 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
979 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
980 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Version The source version to copy from |
981 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
982 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Sharing Object permissions (optional) |
983 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Public Object is publicly accessible (optional) |
984 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Meta-* Optional user defined metadata |
985 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
986 | 8f9976c6 | Constantinos Venetsanopoulos | |
987 | 8f9976c6 | Constantinos Venetsanopoulos | :sup:`*` *When using django locally with the supplied web server, use the ignore_content_type parameter, or do provide a valid Content-Type, as a type of text/plain is applied by default to all requests. Client software should always state ignore_content_type, except when a Content-Type is explicitly defined by the user.* |
988 | 8f9976c6 | Constantinos Venetsanopoulos | |
989 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
990 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
991 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
992 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional conflict response type (can be ``json`` or ``xml``) |
993 | 8f9976c6 | Constantinos Venetsanopoulos | ignore_content_type Ignore the supplied Content-Type |
994 | 87a157c1 | Sofia Papagiannaki | delimiter Optional copy objects starting with object's path and delimiter |
995 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
996 | 8f9976c6 | Constantinos Venetsanopoulos | |
997 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
998 | 8f9976c6 | Constantinos Venetsanopoulos | |
999 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1000 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
1001 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1002 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's new version |
1003 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1004 | 8f9976c6 | Constantinos Venetsanopoulos | |
1005 | 8f9976c6 | Constantinos Venetsanopoulos | | |
1006 | 8f9976c6 | Constantinos Venetsanopoulos | |
1007 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1008 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
1009 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1010 | 8f9976c6 | Constantinos Venetsanopoulos | 201 (Created) The object has been created |
1011 | 8f9976c6 | Constantinos Venetsanopoulos | 413 (Request Entity Too Large) Insufficient quota to complete the request |
1012 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1013 | 8f9976c6 | Constantinos Venetsanopoulos | |
1014 | 8f9976c6 | Constantinos Venetsanopoulos | |
1015 | 8f9976c6 | Constantinos Venetsanopoulos | MOVE |
1016 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
1017 | 8f9976c6 | Constantinos Venetsanopoulos | |
1018 | 8f9976c6 | Constantinos Venetsanopoulos | Same as ``COPY``, without the ``X-Source-Version`` request header. The ``MOVE`` operation is always applied on the latest version. |
1019 | 8f9976c6 | Constantinos Venetsanopoulos | |
1020 | 8f9976c6 | Constantinos Venetsanopoulos | |
1021 | 8f9976c6 | Constantinos Venetsanopoulos | POST |
1022 | 8f9976c6 | Constantinos Venetsanopoulos | """" |
1023 | 8f9976c6 | Constantinos Venetsanopoulos | |
1024 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
1025 | 8f9976c6 | Constantinos Venetsanopoulos | Request Header Name Value |
1026 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
1027 | 8f9976c6 | Constantinos Venetsanopoulos | If-Match Proceed if ETags match with object |
1028 | 8f9976c6 | Constantinos Venetsanopoulos | If-None-Match Proceed if ETags don't match with object |
1029 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the data written (optional, to update) |
1030 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object (optional, to update) |
1031 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Range The range of data supplied (optional, to update) |
1032 | 8f9976c6 | Constantinos Venetsanopoulos | Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored) |
1033 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
1034 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
1035 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Object Update with data from the object at path ``/<container>/<object>`` (optional, to update) |
1036 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Account The source account to update from |
1037 | 8f9976c6 | Constantinos Venetsanopoulos | X-Source-Version The source version to update from (optional, to update) |
1038 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Bytes The updated object's final size (optional, when updating) |
1039 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional) |
1040 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Sharing Object permissions (optional) |
1041 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Public Object is publicly accessible (optional) |
1042 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Meta-* Optional user defined metadata |
1043 | 8f9976c6 | Constantinos Venetsanopoulos | ==================== ================================ |
1044 | 8f9976c6 | Constantinos Venetsanopoulos | |
1045 | 8f9976c6 | Constantinos Venetsanopoulos | | |
1046 | 8f9976c6 | Constantinos Venetsanopoulos | |
1047 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
1048 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
1049 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
1050 | 8f9976c6 | Constantinos Venetsanopoulos | format Optional conflict response type (can be ``json`` or ``xml``) |
1051 | 8f9976c6 | Constantinos Venetsanopoulos | update Do not replace metadata (no value parameter) |
1052 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== ============================================ |
1053 | 8f9976c6 | Constantinos Venetsanopoulos | |
1054 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
1055 | 8f9976c6 | Constantinos Venetsanopoulos | |
1056 | 8f9976c6 | Constantinos Venetsanopoulos | 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. |
1057 | 8f9976c6 | Constantinos Venetsanopoulos | |
1058 | 8f9976c6 | Constantinos Venetsanopoulos | To update an object's data: |
1059 | 8f9976c6 | Constantinos Venetsanopoulos | |
1060 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1061 | 8f9976c6 | Constantinos Venetsanopoulos | * 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``). |
1062 | 8f9976c6 | Constantinos Venetsanopoulos | * Set ``Content-Range`` as specified in RFC2616, with the following differences: |
1063 | 8f9976c6 | Constantinos Venetsanopoulos | |
1064 | 8f9976c6 | Constantinos Venetsanopoulos | * Client software MAY omit ``last-byte-pos`` of if the length of the range being transferred is unknown or difficult to determine. |
1065 | 8f9976c6 | Constantinos Venetsanopoulos | * Client software SHOULD not specify the ``instance-length`` (use a ``*``), unless there is a reason for performing a size check at the server. |
1066 | 8f9976c6 | Constantinos Venetsanopoulos | * If ``Content-Range`` used has a ``byte-range-resp-spec = *``, data will be appended to the object. |
1067 | 8f9976c6 | Constantinos Venetsanopoulos | |
1068 | 8f9976c6 | Constantinos Venetsanopoulos | Optionally, truncate the updated object to the desired length with the ``X-Object-Bytes`` header. |
1069 | 8f9976c6 | Constantinos Venetsanopoulos | |
1070 | 8f9976c6 | Constantinos Venetsanopoulos | A data update will trigger an ETag change. Updated ETags may happen asynchronously and appear at the server with a delay. |
1071 | 8f9976c6 | Constantinos Venetsanopoulos | |
1072 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content. No reply headers if only metadata is updated. |
1073 | 8f9976c6 | Constantinos Venetsanopoulos | |
1074 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1075 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
1076 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1077 | 8f9976c6 | Constantinos Venetsanopoulos | ETag The new ETag of the object (data updated) |
1078 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's new version |
1079 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1080 | 8f9976c6 | Constantinos Venetsanopoulos | |
1081 | 8f9976c6 | Constantinos Venetsanopoulos | | |
1082 | 8f9976c6 | Constantinos Venetsanopoulos | |
1083 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1084 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
1085 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1086 | 8f9976c6 | Constantinos Venetsanopoulos | 202 (Accepted) The request has been accepted (not a data update) |
1087 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded (data updated) |
1088 | 6c9df07c | Sofia Papagiannaki | 400 (Bad Request) Invalid ``X-Object-Sharing`` or ``X-Object-Bytes`` header or missing ``Content-Range`` header or invalid source object or source object length is smaller than range length or ``Content-Length`` does not match range length |
1089 | 8f9976c6 | Constantinos Venetsanopoulos | 411 (Length Required) Missing ``Content-Length`` in the request |
1090 | 8f9976c6 | Constantinos Venetsanopoulos | 413 (Request Entity Too Large) Insufficient quota to complete the request |
1091 | 8f9976c6 | Constantinos Venetsanopoulos | 416 (Range Not Satisfiable) The supplied range is invalid |
1092 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1093 | 8f9976c6 | Constantinos Venetsanopoulos | |
1094 | 8f9976c6 | Constantinos Venetsanopoulos | 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 an ``X-Object-Data`` field, as in the following example. The token is passed as a request parameter. :: |
1095 | 8f9976c6 | Constantinos Venetsanopoulos | |
1096 | 6848eae1 | Sofia Papagiannaki | <form method="post" action="https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt?X-Auth-Token=0000" enctype="multipart/form-data"> |
1097 | 8f9976c6 | Constantinos Venetsanopoulos | <input type="file" name="X-Object-Data"> |
1098 | 8f9976c6 | Constantinos Venetsanopoulos | <input type="submit"> |
1099 | 8f9976c6 | Constantinos Venetsanopoulos | </form> |
1100 | 8f9976c6 | Constantinos Venetsanopoulos | |
1101 | 8f9976c6 | Constantinos Venetsanopoulos | 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 (usually, automatically handled by the browser). Metadata, sharing and other object attributes can not be set this way. The response will contain the object's ETag. |
1102 | 8f9976c6 | Constantinos Venetsanopoulos | |
1103 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1104 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
1105 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1106 | 133e3fcf | Sofia Papagiannaki | ETag The MD5 (or the Merkle if MD5 is deactivated) hash of the object |
1107 | 8f9976c6 | Constantinos Venetsanopoulos | X-Object-Version The object's new version |
1108 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1109 | 8f9976c6 | Constantinos Venetsanopoulos | |
1110 | 8f9976c6 | Constantinos Venetsanopoulos | | |
1111 | 8f9976c6 | Constantinos Venetsanopoulos | |
1112 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1113 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
1114 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1115 | 8f9976c6 | Constantinos Venetsanopoulos | 201 (Created) The object has been created |
1116 | 8f9976c6 | Constantinos Venetsanopoulos | 413 (Request Entity Too Large) Insufficient quota to complete the request |
1117 | 8f9976c6 | Constantinos Venetsanopoulos | ============================== ============================== |
1118 | 8f9976c6 | Constantinos Venetsanopoulos | |
1119 | 8f9976c6 | Constantinos Venetsanopoulos | |
1120 | 8f9976c6 | Constantinos Venetsanopoulos | DELETE |
1121 | 8f9976c6 | Constantinos Venetsanopoulos | """""" |
1122 | 8f9976c6 | Constantinos Venetsanopoulos | |
1123 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
1124 | 8f9976c6 | Constantinos Venetsanopoulos | Request Parameter Name Value |
1125 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
1126 | 8f9976c6 | Constantinos Venetsanopoulos | until Optional timestamp |
1127 | 87a157c1 | Sofia Papagiannaki | delimiter Optional delete also objects starting with object's path and delimiter |
1128 | 8f9976c6 | Constantinos Venetsanopoulos | ====================== =================================== |
1129 | 8f9976c6 | Constantinos Venetsanopoulos | |
1130 | 87a157c1 | Sofia Papagiannaki | If ``until`` is defined, the object is "purged" up to that time (the history up to then is deleted). If also ``delimiter`` is defined, purge is applied only on the object. |
1131 | 8f9976c6 | Constantinos Venetsanopoulos | |
1132 | 8f9976c6 | Constantinos Venetsanopoulos | No reply content/headers. |
1133 | 8f9976c6 | Constantinos Venetsanopoulos | |
1134 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
1135 | 8f9976c6 | Constantinos Venetsanopoulos | Return Code Description |
1136 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
1137 | 8f9976c6 | Constantinos Venetsanopoulos | 204 (No Content) The request succeeded |
1138 | 8f9976c6 | Constantinos Venetsanopoulos | =========================== ============================== |
1139 | 8f9976c6 | Constantinos Venetsanopoulos | |
1140 | 8f9976c6 | Constantinos Venetsanopoulos | Sharing and Public Objects |
1141 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
1142 | 8f9976c6 | Constantinos Venetsanopoulos | |
1143 | 8f9976c6 | Constantinos Venetsanopoulos | Read and write control in Pithos is managed by setting appropriate permissions with the ``X-Object-Sharing`` header. The permissions are applied using directory-based inheritance. A directory is an object with the corresponding content type. The default delimiter is ``/``. Thus, each set of authorization directives is applied to all objects in the directory object where the corresponding ``X-Object-Sharing`` header is defined. If there are nested/overlapping permissions, the closest to the object is applied. 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. |
1144 | 8f9976c6 | Constantinos Venetsanopoulos | |
1145 | 8f9976c6 | Constantinos Venetsanopoulos | 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. The ``X-Object-Allowed-To`` header lists the actions allowed on an object, if it does not belong to the requesting user. |
1146 | 8f9976c6 | Constantinos Venetsanopoulos | |
1147 | 6fe32fb6 | Sofia Papagiannaki | Shared objects that are also public do not expose the ``X-Object-Public`` meta information. |
1148 | 6fe32fb6 | Sofia Papagiannaki | |
1149 | 8f9976c6 | Constantinos Venetsanopoulos | 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): |
1150 | 8f9976c6 | Constantinos Venetsanopoulos | |
1151 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1152 | 8f9976c6 | Constantinos Venetsanopoulos | Reply Header Name Value |
1153 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1154 | 8f9976c6 | Constantinos Venetsanopoulos | ETag The ETag of the object |
1155 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Length The size of the data returned |
1156 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Type The MIME content type of the object |
1157 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Range The range of data included (only on a single range request) |
1158 | 8f9976c6 | Constantinos Venetsanopoulos | Last-Modified The last object modification date (regardless of version) |
1159 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Encoding The encoding of the object (optional) |
1160 | 8f9976c6 | Constantinos Venetsanopoulos | Content-Disposition The presentation style of the object (optional) |
1161 | 8f9976c6 | Constantinos Venetsanopoulos | ========================== =============================== |
1162 | 8f9976c6 | Constantinos Venetsanopoulos | |
1163 | 8f9976c6 | Constantinos Venetsanopoulos | Public objects are not included and do not influence cross-user listings. They are, however, readable by all users. |
1164 | 8f9976c6 | Constantinos Venetsanopoulos | |
1165 | 8f9976c6 | Constantinos Venetsanopoulos | Summary |
1166 | 8f9976c6 | Constantinos Venetsanopoulos | ^^^^^^^ |
1167 | 8f9976c6 | Constantinos Venetsanopoulos | |
1168 | 8f9976c6 | Constantinos Venetsanopoulos | List of differences from the OOS API: |
1169 | 8f9976c6 | Constantinos Venetsanopoulos | |
1170 | 8f9976c6 | Constantinos Venetsanopoulos | * Support for ``X-Account-Meta-*`` style headers at the account level. Use ``POST`` to update. |
1171 | 8f9976c6 | Constantinos Venetsanopoulos | * Support for ``X-Container-Meta-*`` style headers at the container level. Can be set when creating via ``PUT``. Use ``POST`` to update. |
1172 | 8f9976c6 | Constantinos Venetsanopoulos | * Header ``X-Container-Object-Meta`` at the container level and parameter ``meta`` in container listings. (**TBD**) |
1173 | 8f9976c6 | Constantinos Venetsanopoulos | * Account and container policies to manage behavior and limits. Container behavior overrides account settings. Account quota sets the maximum bytes limit, regardless of container values. |
1174 | 8f9976c6 | Constantinos Venetsanopoulos | * Headers ``X-Container-Block-*`` at the container level, exposing the underlying storage characteristics. |
1175 | 8f9976c6 | Constantinos Venetsanopoulos | * All metadata replies, at all levels, include latest modification information. |
1176 | 8f9976c6 | Constantinos Venetsanopoulos | * At all levels, a ``HEAD`` or ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers. |
1177 | 8f9976c6 | Constantinos Venetsanopoulos | * Container/object lists include more fields if the reply is of type JSON/XML. Some names are kept to their OOS API equivalents for compatibility. |
1178 | 8f9976c6 | Constantinos Venetsanopoulos | * Option to include only shared containers/objects in listings. |
1179 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1180 | 8f9976c6 | Constantinos Venetsanopoulos | * Multi-range object ``GET`` support as outlined in RFC2616. |
1181 | 8f9976c6 | Constantinos Venetsanopoulos | * Object hashmap retrieval through ``GET`` and the ``format`` parameter. |
1182 | 8f9976c6 | Constantinos Venetsanopoulos | * Object create via hashmap through ``PUT`` and the ``format`` parameter. |
1183 | 8f9976c6 | Constantinos Venetsanopoulos | * The object's Merkle hash is always returned in the ``X-Object-Hash`` header. |
1184 | 8f9976c6 | Constantinos Venetsanopoulos | * The object's UUID is always returned in the ``X-Object-UUID`` header. The UUID remains unchanged, even when the object's data or metadata changes, or the object is moved to another path (is renamed). A new UUID is assigned when creating or copying an object. |
1185 | 8f9976c6 | Constantinos Venetsanopoulos | * Object create using ``POST`` to support standard HTML forms. |
1186 | 8f9976c6 | Constantinos Venetsanopoulos | * 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``. |
1187 | 8f9976c6 | Constantinos Venetsanopoulos | * Include new version identifier in replies for object replace/change requests. |
1188 | 8f9976c6 | Constantinos Venetsanopoulos | * Object ``MOVE`` support and ``ignore_content_type`` parameter in both ``COPY`` and ``MOVE``. |
1189 | 8f9976c6 | Constantinos Venetsanopoulos | * Conditional object create/update operations, using ``If-Match`` and ``If-None-Match`` headers. |
1190 | 8f9976c6 | Constantinos Venetsanopoulos | * Time-variant account/container listings via the ``until`` parameter. |
1191 | 8f9976c6 | Constantinos Venetsanopoulos | * Object versions - parameter ``version`` in ``HEAD``/``GET`` (list versions with ``GET``), ``X-Object-Version-*`` meta in replies, ``X-Source-Version`` in ``PUT``/``COPY``. |
1192 | 8f9976c6 | Constantinos Venetsanopoulos | * Sharing/publishing with ``X-Object-Sharing``, ``X-Object-Public`` at the object level. Cross-user operations are allowed - controlled by sharing directives. Available actions in cross-user requests are reported with ``X-Object-Allowed-To``. Permissions may include groups defined with ``X-Account-Group-*`` at the account level. These apply to the object - not its versions. |
1193 | 8f9976c6 | Constantinos Venetsanopoulos | * Support for directory-based inheritance when enforcing permissions. Parent object carrying the authorization directives is reported in ``X-Object-Shared-By``. |
1194 | 8f9976c6 | Constantinos Venetsanopoulos | * Copy and move between accounts with ``X-Source-Account`` and ``Destination-Account`` headers. |
1195 | 8f9976c6 | Constantinos Venetsanopoulos | * Large object support with ``X-Object-Manifest``. |
1196 | 8f9976c6 | Constantinos Venetsanopoulos | * Trace the user that created/modified an object with ``X-Object-Modified-By``. |
1197 | 8f9976c6 | Constantinos Venetsanopoulos | * Purge container/object history with the ``until`` parameter in ``DELETE``. |
1198 | eb56e157 | Sofia Papagiannaki | * Bulk COPY/MOVE/DELETE objects starting with prefix |
1199 | 8f9976c6 | Constantinos Venetsanopoulos | |
1200 | 8f9976c6 | Constantinos Venetsanopoulos | Clarifications/suggestions: |
1201 | 8f9976c6 | Constantinos Venetsanopoulos | |
1202 | 8f9976c6 | Constantinos Venetsanopoulos | * All non-ASCII characters in headers should be URL-encoded. |
1203 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1204 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1205 | 8f9976c6 | Constantinos Venetsanopoulos | * A ``GET`` reply for a level will include all headers of the corresponding ``HEAD`` request. |
1206 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1207 | 8f9976c6 | Constantinos Venetsanopoulos | * The ``Accept`` header may be used in requests instead of the ``format`` parameter to specify the desired request/reply format. The parameter overrides the header. |
1208 | 8f9976c6 | Constantinos Venetsanopoulos | * Container/object lists use a ``200`` return code if the reply is of type JSON/XML. The reply will include an empty JSON/XML. |
1209 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1210 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1211 | 8f9976c6 | Constantinos Venetsanopoulos | * A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers. |
1212 | 8f9976c6 | Constantinos Venetsanopoulos | * 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. |
1213 | dad708b4 | Antony Chazapis | |
1214 | dad708b4 | Antony Chazapis | Recommended Practices and Examples |
1215 | dad708b4 | Antony Chazapis | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
1216 | dad708b4 | Antony Chazapis | |
1217 | dad708b4 | Antony Chazapis | Assuming an authentication token is obtained, the following high-level operations are available - shown with ``curl``: |
1218 | dad708b4 | Antony Chazapis | |
1219 | dad708b4 | Antony Chazapis | * Get account information :: |
1220 | dad708b4 | Antony Chazapis | |
1221 | dad708b4 | Antony Chazapis | curl -X HEAD -D - \ |
1222 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1223 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid |
1224 | dad708b4 | Antony Chazapis | |
1225 | dad708b4 | Antony Chazapis | * List available containers :: |
1226 | dad708b4 | Antony Chazapis | |
1227 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1228 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1229 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid |
1230 | dad708b4 | Antony Chazapis | |
1231 | dad708b4 | Antony Chazapis | * Get container information :: |
1232 | dad708b4 | Antony Chazapis | |
1233 | dad708b4 | Antony Chazapis | curl -X HEAD -D - \ |
1234 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1235 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos |
1236 | dad708b4 | Antony Chazapis | |
1237 | dad708b4 | Antony Chazapis | * Add a new container :: |
1238 | dad708b4 | Antony Chazapis | |
1239 | dad708b4 | Antony Chazapis | curl -X PUT -D - \ |
1240 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1241 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/test |
1242 | dad708b4 | Antony Chazapis | |
1243 | dad708b4 | Antony Chazapis | * Delete a container :: |
1244 | dad708b4 | Antony Chazapis | |
1245 | dad708b4 | Antony Chazapis | curl -X DELETE -D - \ |
1246 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1247 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/test |
1248 | dad708b4 | Antony Chazapis | |
1249 | dad708b4 | Antony Chazapis | * List objects in a container :: |
1250 | dad708b4 | Antony Chazapis | |
1251 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1252 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1253 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos |
1254 | dad708b4 | Antony Chazapis | |
1255 | dad708b4 | Antony Chazapis | * List objects in a container (extended reply) :: |
1256 | dad708b4 | Antony Chazapis | |
1257 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1258 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1259 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos?format=json |
1260 | dad708b4 | Antony Chazapis | |
1261 | dad708b4 | Antony Chazapis | It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header. |
1262 | dad708b4 | Antony Chazapis | |
1263 | dad708b4 | Antony Chazapis | * List metadata keys used by objects in a container |
1264 | dad708b4 | Antony Chazapis | |
1265 | dad708b4 | Antony Chazapis | Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``). (**TBD**) |
1266 | dad708b4 | Antony Chazapis | |
1267 | dad708b4 | Antony Chazapis | * List objects in a container having a specific meta defined :: |
1268 | dad708b4 | Antony Chazapis | |
1269 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1270 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1271 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos?meta=favorites |
1272 | dad708b4 | Antony Chazapis | |
1273 | dad708b4 | Antony Chazapis | * Retrieve an object :: |
1274 | dad708b4 | Antony Chazapis | |
1275 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1276 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1277 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos/README.txt |
1278 | dad708b4 | Antony Chazapis | |
1279 | dad708b4 | Antony Chazapis | * Retrieve an object (specific ranges of data) :: |
1280 | dad708b4 | Antony Chazapis | |
1281 | dad708b4 | Antony Chazapis | curl -X GET -D - \ |
1282 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1283 | dad708b4 | Antony Chazapis | -H "Range: bytes=0-9" \ |
1284 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos/README.txt |
1285 | dad708b4 | Antony Chazapis | |
1286 | dad708b4 | 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``. |
1287 | dad708b4 | Antony Chazapis | |
1288 | dad708b4 | Antony Chazapis | * Add a new object (folder type) (**TBD**) :: |
1289 | dad708b4 | Antony Chazapis | |
1290 | dad708b4 | Antony Chazapis | curl -X PUT -D - \ |
1291 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1292 | dad708b4 | Antony Chazapis | -H "Content-Type: application/directory" \ |
1293 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos/folder |
1294 | dad708b4 | Antony Chazapis | |
1295 | dad708b4 | Antony Chazapis | * Add a new object :: |
1296 | dad708b4 | Antony Chazapis | |
1297 | dad708b4 | Antony Chazapis | curl -X PUT -D - \ |
1298 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1299 | dad708b4 | Antony Chazapis | -H "Content-Type: text/plain" \ |
1300 | dad708b4 | Antony Chazapis | -T EXAMPLE.txt |
1301 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/pithos/folder/EXAMPLE.txt |
1302 | dad708b4 | Antony Chazapis | |
1303 | dad708b4 | Antony Chazapis | * Update an object :: |
1304 | dad708b4 | Antony Chazapis | |
1305 | dad708b4 | Antony Chazapis | curl -X POST -D - \ |
1306 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1307 | dad708b4 | Antony Chazapis | -H "Content-Length: 10" \ |
1308 | dad708b4 | Antony Chazapis | -H "Content-Type: application/octet-stream" \ |
1309 | dad708b4 | Antony Chazapis | -H "Content-Range: bytes 10-19/*" \ |
1310 | dad708b4 | Antony Chazapis | -d "0123456789" \ |
1311 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |
1312 | dad708b4 | Antony Chazapis | |
1313 | dad708b4 | Antony Chazapis | This will update bytes 10-19 with the data specified. |
1314 | dad708b4 | Antony Chazapis | |
1315 | dad708b4 | Antony Chazapis | * Update an object (append) :: |
1316 | dad708b4 | Antony Chazapis | |
1317 | dad708b4 | Antony Chazapis | curl -X POST -D - \ |
1318 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1319 | dad708b4 | Antony Chazapis | -H "Content-Length: 10" \ |
1320 | dad708b4 | Antony Chazapis | -H "Content-Type: application/octet-stream" \ |
1321 | dad708b4 | Antony Chazapis | -H "Content-Range: bytes */*" \ |
1322 | dad708b4 | Antony Chazapis | -d "0123456789" \ |
1323 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |
1324 | dad708b4 | Antony Chazapis | |
1325 | dad708b4 | Antony Chazapis | * Update an object (truncate) :: |
1326 | dad708b4 | Antony Chazapis | |
1327 | dad708b4 | Antony Chazapis | curl -X POST -D - \ |
1328 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1329 | dad708b4 | Antony Chazapis | -H "X-Source-Object: /folder/EXAMPLE.txt" \ |
1330 | dad708b4 | Antony Chazapis | -H "Content-Range: bytes 0-0/*" \ |
1331 | dad708b4 | Antony Chazapis | -H "X-Object-Bytes: 0" \ |
1332 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |
1333 | dad708b4 | Antony Chazapis | |
1334 | dad708b4 | Antony Chazapis | This will truncate the object to 0 bytes. |
1335 | dad708b4 | Antony Chazapis | |
1336 | dad708b4 | Antony Chazapis | * Add object metadata :: |
1337 | dad708b4 | Antony Chazapis | |
1338 | dad708b4 | Antony Chazapis | curl -X POST -D - \ |
1339 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1340 | dad708b4 | Antony Chazapis | -H "X-Object-Meta-First: first_meta_value" \ |
1341 | dad708b4 | Antony Chazapis | -H "X-Object-Meta-Second: second_meta_value" \ |
1342 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |
1343 | dad708b4 | Antony Chazapis | |
1344 | dad708b4 | Antony Chazapis | * Delete object metadata :: |
1345 | dad708b4 | Antony Chazapis | |
1346 | dad708b4 | Antony Chazapis | curl -X POST -D - \ |
1347 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1348 | dad708b4 | Antony Chazapis | -H "X-Object-Meta-First: first_meta_value" \ |
1349 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |
1350 | dad708b4 | Antony Chazapis | |
1351 | dad708b4 | Antony Chazapis | Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all metadata. |
1352 | dad708b4 | Antony Chazapis | |
1353 | dad708b4 | Antony Chazapis | * Delete an object :: |
1354 | dad708b4 | Antony Chazapis | |
1355 | dad708b4 | Antony Chazapis | curl -X DELETE -D - \ |
1356 | dad708b4 | Antony Chazapis | -H "X-Auth-Token: 0000" \ |
1357 | 6848eae1 | Sofia Papagiannaki | https://storage.example.synnefo.org/pithos/object-store/v1.0/user-uuid/folder/EXAMPLE.txt |