code.grnet.gr Git - pithos/blob - docs/source/devguide.rst

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