+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).
+
+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.
+
+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, 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``.
+
+Uploading and downloading data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By using hashmaps to upload and download objects the corresponding operations can complete much faster.
+
+In the case of an upload, only the missing blocks will be submitted to the server:
+
+* Calculate the hash value for each block of the object to be uploaded. Use the hash algorithm and block size of the destination container.
+* Send a hashmap ``PUT`` request for the object.
+
+ * Server responds with status ``201`` (Created):
+
+ * Blocks are already on the server. The object has been created. Done.
+
+ * Server responds with status ``409`` (Conflict):
+
+ * Server's response body contains the hashes of the blocks that do not exist on the server.
+ * For each hash value in the server's response (or all hashes together):
+
+ * Send a ``POST`` request to the destination container with the corresponding data.
+
+* Repeat hashmap ``PUT``. Fail if the server's response is not ``201``.
+
+Consulting hashmaps when downloading allows for resuming partially transferred objects. The client should retrieve the hashmap from the server and compare it with the hashmap computed from the respective local file. Any missing parts can be downloaded with ``GET`` requests with the additional ``Range`` header.
+
+Syncing
+^^^^^^^
+
+Consider the following algorithm for synchronizing a local folder with the server. The "state" is the complete object listing, with the corresponding attributes.
+
+::
+
+ L: local state (stored state from last sync with the server)
+ C: current state (state computed right before sync)
+ S: server state
+
+ if C == L:
+ # No local changes
+ if S == L:
+ # No remote changes, nothing to do
+ else:
+ # Update local state to match that of the server
+ L = S
+ else:
+ # We have local changes
+ if S == L:
+ # No remote changes, update the server
+ S = C
+ L = S
+ else:
+ # Both we and server have changes
+ if C == S:
+ # We were lucky, we did the same change
+ L = S
+ else:
+ # We have conflicting changes
+ resolve conflict
+
+Notes:
+
+* States represent file hashes (either MD5 or Merkle). Deleted or non-existing files are assumed to have a magic hash (e.g. empty string).
+* Updating a state (either local or remote) implies downloading, uploading or deleting the appropriate file.
+
+Recommended Practices and Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming an authentication token is obtained, the following high-level operations are available - shown with ``curl``:
+
+* Get account information ::
+
+ curl -X HEAD -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user
+
+* List available containers ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user
+
+* Get container information ::
+
+ curl -X HEAD -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/pithos
+
+* Add a new container ::
+
+ curl -X PUT -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/test
+
+* Delete a container ::
+
+ curl -X DELETE -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/test
+
+* List objects in a container ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/pithos
+
+* List objects in a container (extended reply) ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/pithos?format=json
+
+ It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header.
+
+* List metadata keys used by objects in a container
+
+ Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``). (**TBD**)
+
+* List objects in a container having a specific meta defined ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/pithos?meta=favorites
+
+* Retrieve an object ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
+
+* Retrieve an object (specific ranges of data) ::
+
+ curl -X GET -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "Range: bytes=0-9" \
+ https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
+
+ 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``.
+
+* Add a new object (folder type) (**TBD**) ::
+
+ curl -X PUT -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "Content-Type: application/directory" \
+ https://pithos.dev.grnet.gr/v1/user/pithos/folder
+
+* Add a new object ::
+
+ curl -X PUT -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "Content-Type: text/plain" \
+ -T EXAMPLE.txt
+ https://pithos.dev.grnet.gr/v1/user/pithos/folder/EXAMPLE.txt
+
+* Update an object ::
+
+ curl -X POST -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "Content-Length: 10" \
+ -H "Content-Type: application/octet-stream" \
+ -H "Content-Range: bytes 10-19/*" \
+ -d "0123456789" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+ This will update bytes 10-19 with the data specified.
+
+* Update an object (append) ::
+
+ curl -X POST -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "Content-Length: 10" \
+ -H "Content-Type: application/octet-stream" \
+ -H "Content-Range: bytes */*" \
+ -d "0123456789" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+* Update an object (truncate) ::
+
+ curl -X POST -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "X-Source-Object: /folder/EXAMPLE.txt" \
+ -H "Content-Range: bytes 0-0/*" \
+ -H "X-Object-Bytes: 0" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+ This will truncate the object to 0 bytes.
+
+* Add object metadata ::
+
+ curl -X POST -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "X-Object-Meta-First: first_meta_value" \
+ -H "X-Object-Meta-Second: second_meta_value" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+* Delete object metadata ::
+
+ curl -X POST -D - \
+ -H "X-Auth-Token: 0000" \
+ -H "X-Object-Meta-First: first_meta_value" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
+
+ Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all metadata.
+
+* Delete an object ::
+
+ curl -X DELETE -D - \
+ -H "X-Auth-Token: 0000" \
+ https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt