Revision f6c97079 docs/source/devguide.rst
b/docs/source/devguide.rst | ||
---|---|---|
25 | 25 |
========================= ================================ |
26 | 26 |
Revision Description |
27 | 27 |
========================= ================================ |
28 |
0.5 (July 16, 2011) Object update from another object's data.
|
|
28 |
0.5 (July 19, 2011) Object update from another object's data.
|
|
29 | 29 |
\ Support object truncate. |
30 | 30 |
\ Create object using a standard HTML form. |
31 | 31 |
\ Purge container/object history. |
32 |
\ List other accounts that share objects with a user. |
|
32 | 33 |
0.4 (July 01, 2011) Object permissions and account groups. |
33 | 34 |
\ Control versioning behavior and container quotas with container policy directives. |
34 | 35 |
\ Support updating/deleting individual metadata with ``POST``. |
... | ... | |
77 | 78 |
========= ================== |
78 | 79 |
Operation Description |
79 | 80 |
========= ================== |
80 |
GET Authentication. This is kept for compatibility with the OOS API
|
|
81 |
GET Authentication (for compatibility with the OOS API) or list allowed accounts
|
|
81 | 82 |
========= ================== |
82 | 83 |
|
83 | 84 |
GET |
... | ... | |
91 | 92 |
204 (No Content) The request succeeded |
92 | 93 |
================ ===================== |
93 | 94 |
|
95 |
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. |
|
96 |
|
|
97 |
====================== ========================= |
|
98 |
Request Parameter Name Value |
|
99 |
====================== ========================= |
|
100 |
limit The amount of results requested (default is 10000) |
|
101 |
marker Return containers with name lexicographically after marker |
|
102 |
format Optional extended reply type (can be ``json`` or ``xml``) |
|
103 |
====================== ========================= |
|
104 |
|
|
105 |
The reply is a list of account names. |
|
106 |
If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format. |
|
107 |
For each account, the information will include the following (names will be in lower case and with hyphens replaced with underscores): |
|
108 |
|
|
109 |
=========================== ============================ |
|
110 |
Name Description |
|
111 |
=========================== ============================ |
|
112 |
name The name of the account |
|
113 |
last_modified The last container modification date (regardless of ``until``) |
|
114 |
=========================== ============================ |
|
115 |
|
|
116 |
Example ``format=json`` reply: |
|
117 |
|
|
118 |
:: |
|
119 |
|
|
120 |
[{"name": "user", "last_modified": "2011-07-19T10:48:16"}, ...] |
|
121 |
|
|
122 |
Example ``format=xml`` reply: |
|
123 |
|
|
124 |
:: |
|
125 |
|
|
126 |
<?xml version="1.0" encoding="UTF-8"?> |
|
127 |
<accounts> |
|
128 |
<account> |
|
129 |
<name>user</name> |
|
130 |
<last_modified>2011-07-19T10:48:16</last_modified> |
|
131 |
</account> |
|
132 |
<account>...</account> |
|
133 |
</accounts> |
|
134 |
|
|
135 |
=========================== ===================== |
|
136 |
Return Code Description |
|
137 |
=========================== ===================== |
|
138 |
200 (OK) The request succeeded |
|
139 |
204 (No Content) The account has no containers (only for non-extended replies) |
|
140 |
=========================== ===================== |
|
141 |
|
|
142 |
Will use a ``200`` return code if the reply is of type json/xml. |
|
94 | 143 |
|
95 | 144 |
Account Level |
96 | 145 |
^^^^^^^^^^^^^ |
... | ... | |
114 | 163 |
until Optional timestamp |
115 | 164 |
====================== =================================== |
116 | 165 |
|
117 |
|
|
|
166 |
Cross-user requests are not allowed to use ``until`` and only include the account modification date in the reply.
|
|
118 | 167 |
|
119 | 168 |
========================== ===================== |
120 | 169 |
Reply Header Name Value |
... | ... | |
161 | 210 |
====================== ========================= |
162 | 211 |
|
163 | 212 |
The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included. |
213 |
Cross-user requests are not allowed to use ``until`` and only include the account/container modification dates in the reply. |
|
214 |
|
|
164 | 215 |
If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format. |
165 | 216 |
For each container, the information will include all container metadata (names will be in lower case and with hyphens replaced with underscores): |
166 | 217 |
|
... | ... | |
245 | 296 |
until Optional timestamp |
246 | 297 |
====================== =================================== |
247 | 298 |
|
248 |
|
|
|
299 |
Cross-user requests are not allowed to use ``until`` and only include the container modification date in the reply.
|
|
249 | 300 |
|
250 | 301 |
=========================== =============================== |
251 | 302 |
Reply Header Name Value |
... | ... | |
300 | 351 |
The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix. |
301 | 352 |
|
302 | 353 |
The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included. |
354 |
Cross-user requests are not allowed to use ``until`` and include the following limited set of headers in the reply: |
|
355 |
|
|
356 |
=========================== =============================== |
|
357 |
Reply Header Name Value |
|
358 |
=========================== =============================== |
|
359 |
X-Container-Block-Size The block size used by the storage backend |
|
360 |
X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps |
|
361 |
X-Container-Object-Meta A list with all meta keys used by allowed objects (**TBD**) |
|
362 |
Last-Modified The last container modification date |
|
363 |
=========================== =============================== |
|
364 |
|
|
303 | 365 |
If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format. |
304 | 366 |
For each object, the information will include all object metadata (names will be in lower case and with hyphens replaced with underscores): |
305 | 367 |
|
... | ... | |
791 | 853 |
|
792 | 854 |
Read and write control in Pithos is managed by setting appropriate permissions with the ``X-Object-Sharing`` header. The permissions are applied using prefix-based inheritance. Thus, each set of authorization directives is applied to all objects sharing the same prefix with the object where the corresponding ``X-Object-Sharing`` header is defined. For simplicity, nested/overlapping permissions are not allowed. Setting ``X-Object-Sharing`` will fail, if the object is already "covered", or another object with a longer common-prefix name already has permissions. When retrieving an object, the ``X-Object-Shared-By`` header reports where it gets its permissions from. If not present, the object is the actual source of authorization directives. |
793 | 855 |
|
794 |
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). |
|
856 |
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. |
|
857 |
|
|
858 |
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): |
|
795 | 859 |
|
796 | 860 |
========================== =============================== |
797 | 861 |
Reply Header Name Value |
... | ... | |
805 | 869 |
Content-Disposition The presentation style of the object (optional) |
806 | 870 |
========================== =============================== |
807 | 871 |
|
872 |
Public objects are not included and do not influence cross-user listings. They are, however, readable by all users. |
|
873 |
|
|
808 | 874 |
Summary |
809 | 875 |
^^^^^^^ |
810 | 876 |
|
... | ... | |
827 | 893 |
* Object ``MOVE`` support. |
828 | 894 |
* Time-variant account/container listings via the ``until`` parameter. |
829 | 895 |
* Object versions - parameter ``version`` in ``HEAD``/``GET`` (list versions with ``GET``), ``X-Object-Version-*`` meta in replies, ``X-Source-Version`` in ``PUT``/``COPY``. |
830 |
* Sharing/publishing with ``X-Object-Sharing``, ``X-Object-Public`` at the object level. Permissions may include groups defined with ``X-Account-Group-*`` at the account level. These apply to the object - not its versions. |
|
896 |
* Sharing/publishing with ``X-Object-Sharing``, ``X-Object-Public`` at the object level. Cross-user operations are allowed - controlled by sharing directives. Permissions may include groups defined with ``X-Account-Group-*`` at the account level. These apply to the object - not its versions.
|
|
831 | 897 |
* Support for prefix-based inheritance when enforcing permissions. Parent object carrying the authorization directives is reported in ``X-Object-Shared-By``. |
832 | 898 |
* Large object support with ``X-Object-Manifest``. |
833 | 899 |
* Trace the user that created/modified an object with ``X-Object-Modified-By``. |
Also available in: Unified diff