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