--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# Pithos documentation build configuration file, created by
+# sphinx-quickstart on Wed May 18 12:42:48 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('..'))
+
+from pithos import settings
+from django.core.management import setup_environ
+setup_environ(settings)
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Pithos'
+copyright = u'2011, Pithos Storage Team'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2'
+# The full version, including alpha/beta/rc tags.
+release = '2'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'nature'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Pithosdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'Pithos.tex', u'Pithos Documentation',
+ u'Pithos Storage Team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'pithos', u'Pithos Documentation',
+ [u'Pithos Storage Team'], 1)
+]
+
+
+autodoc_default_flags = ['members']
--- /dev/null
+Pithos v2 Developer Guide
+=========================
+
+Introduction
+------------
+
+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.
+
+This document's goals are:
+
+* Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls
+* Specify metadata semantics and user interface guidelines for a common experience across client software implementations
+
+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.
+
+Whatever marked as to be determined (**TBD**), should not be considered by implementors.
+
+Document Revisions
+^^^^^^^^^^^^^^^^^^
+
+========================= ================================
+Revision Description
+========================= ================================
+0.2 (May 25, 2011) Add object meta listing and filtering in containers.
+\ Support for multi-range object GET requests.
+0.1 (May 17, 2011) Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011).
+========================= ================================
+
+The Pithos API
+--------------
+
+The URI requests supported by Pithos follow one of the following forms:
+
+* Top level: ``https://hostname/v1/``
+* Account level: ``https://hostname/v1/<account>``
+* Container level: ``https://hostname/v1/<account>/<container>``
+* Object level: ``https://hostname/v1/<account>/<container>/<object>``
+
+All requests must include an ``X-Auth-Token``, except from those that refer to publicly available files (**TBD**). The process of obtaining the token is still to be determined (**TBD**).
+
+The allowable request operations and corresponding return codes per level are presented in the remainder of this chapter. Common to all requests are the following return codes.
+
+========================= ================================
+Return Code Description
+========================= ================================
+400 (Bad Request) The request is invalid
+401 (Unauthorized) Request not allowed
+404 (Not Found) The requested resource was not found
+503 (Service Unavailable) The request cannot be completed because of an internal error
+========================= ================================
+
+Top Level
+^^^^^^^^^
+
+List of operations:
+
+========= ==================
+Operation Description
+========= ==================
+GET Authentication. This is kept for compatibility with the OOS API
+========= ==================
+
+GET
+"""
+
+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.
+
+================ =====================
+Return Code Description
+================ =====================
+204 (No Content) The request succeeded
+================ =====================
+
+
+Account Level
+^^^^^^^^^^^^^
+
+List of operations:
+
+========= ==================
+Operation Description
+========= ==================
+HEAD Retrieve account metadata
+GET List containers
+POST Update account metadata
+========= ==================
+
+HEAD
+""""
+
+No request parameters/headers.
+
+========================== =====================
+Reply Header Name Value
+========================== =====================
+X-Account-Container-Count The total number of containers
+X-Account-Object-Count The total number of objects (**TBD**)
+X-Account-Bytes-Used The total number of bytes stored
+X-Account-Bytes-Remaining The total number of bytes remaining (**TBD**)
+X-Account-Last-Login The last login (**TBD**)
+X-Account-Meta-* Optional user defined metadata
+Last-Modified The last object modification date
+========================== =====================
+
+|
+
+================ =====================
+Return Code Description
+================ =====================
+204 (No Content) The request succeeded
+================ =====================
+
+
+GET
+"""
+
+==================== ===========================
+Request Header Name Value
+==================== ===========================
+If-Modified-Since Retrieve if account has changed since provided timestamp
+If-Unmodified-Since Retrieve if account has not changed since provided timestamp
+==================== ===========================
+
+|
+
+====================== =========================
+Request Parameter Name Value
+====================== =========================
+limit The amount of results requested (default is 10000)
+marker Return containers with name lexicographically after marker
+format Optional extended reply type (can be ``json`` or ``xml``)
+====================== =========================
+
+The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included.
+If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format.
+For each container, the information will include all container metadata (names will be in lower case and with hyphens replaced with underscores):
+
+=================== ============================
+Name Description
+=================== ============================
+name The name of the container
+count The number of objects inside the container
+bytes The total size of the objects inside the container
+last_modified The last object modification date
+x_container_meta_* Optional user defined metadata
+=================== ============================
+
+For examples of container details returned in JSON/XML formats refer to the OOS API documentation.
+
+================ =====================
+Return Code Description
+================ =====================
+200 (OK) The request succeeded
+204 (No Content) The account has no containers (only for non-extended replies)
+================ =====================
+
+Will use a ``200`` return code if the reply is of type json/xml.
+
+
+POST
+""""
+
+==================== ===========================
+Request Header Name Value
+==================== ===========================
+X-Account-Meta-* Optional user defined metadata
+==================== ===========================
+
+No reply content/headers.
+
+The update operation will overwrite all user defined metadata.
+
+================ ===============================
+Return Code Description
+================ ===============================
+202 (Accepted) The request has been accepted
+================ ===============================
+
+
+Container Level
+^^^^^^^^^^^^^^^
+
+List of operations:
+
+========= ============================
+Operation Description
+========= ============================
+HEAD Retrieve container metadata
+GET List objects
+PUT Create/update container
+POST Update container metadata
+DELETE Delete container
+========= ============================
+
+
+HEAD
+""""
+
+No request parameters/headers.
+
+========================== ===============================
+Reply Header Name Value
+========================== ===============================
+X-Container-Object-Count The total number of objects in the container
+X-Container-Bytes-Used The total number of bytes of all objects stored
+X-Container-Meta-* Optional user defined metadata
+X-Container-Object-Meta A list with all meta keys used by objects
+Last-Modified The last object modification date
+========================== ===============================
+
+The keys returned in ``X-Container-Object-Meta`` are all the unique strings after the ``X-Object-Meta-`` prefix.
+
+================ ===============================
+Return Code Description
+================ ===============================
+204 (No Content) The request succeeded
+================ ===============================
+
+
+GET
+"""
+
+==================== ===========================
+Request Header Name Value
+==================== ===========================
+If-Modified-Since Retrieve if container has changed since provided timestamp
+If-Unmodified-Since Retrieve if container has not changed since provided timestamp
+==================== ===========================
+
+|
+
+====================== ===================================
+Request Parameter Name Value
+====================== ===================================
+limit The amount of results requested (default is 10000)
+marker Return containers with name lexicographically after marker
+prefix Return objects starting with prefix
+delimiter Return objects up to the delimiter (discussion follows)
+path Assume ``prefix=path`` and ``delimiter=/``
+format Optional extended reply type (can be ``json`` or ``xml``)
+meta Return objects having the specified meta keys (can be a comma separated list)
+====================== ===================================
+
+The ``path`` parameter overrides ``prefix`` and ``delimiter``. When using ``path``, results will include objects ending in ``delimiter``.
+
+The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix.
+
+The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included.
+If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format.
+For each object, the information will include all object metadata (names will be in lower case and with hyphens replaced with underscores):
+
+=================== ======================================
+Name Description
+=================== ======================================
+name The name of the object
+hash The MD5 hash of the object
+bytes The size of the object
+content_type The MIME content type of the object
+content_encoding The encoding of the object (optional)
+last_modified The last object modification date
+x_object_manifest Large object support
+x_object_meta_* Optional user defined metadata
+=================== ======================================
+
+Extended replies may also include virtual directory markers in separate sections of the ``json`` or ``xml`` results.
+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.
+In JSON results they appear as dictionaries with only a ``"subdir"`` key. In XML results they appear interleaved with ``<object>`` tags as ``<subdir name="..." />``.
+In case there is an object with the same name as a virtual directory marker, the object will be returned.
+
+For examples of object details returned in JSON/XML formats refer to the OOS API documentation.
+
+================ ===============================
+Return Code Description
+================ ===============================
+200 (OK) The request succeeded
+204 (No Content) The account has no containers (only for non-extended replies)
+================ ===============================
+
+Will use a ``200`` return code if the reply is of type json/xml.
+
+
+PUT
+"""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+X-Container-Meta-* Optional user defined metadata
+==================== ================================
+
+No reply content/headers.
+
+================ ===============================
+Return Code Description
+================ ===============================
+201 (Created) The container has been created
+202 (Accepted) The request has been accepted
+================ ===============================
+
+
+POST
+""""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+X-Container-Meta-* Optional user defined metadata
+==================== ================================
+
+No reply content/headers.
+
+The update operation will overwrite all user defined metadata.
+
+================ ===============================
+Return Code Description
+================ ===============================
+202 (Accepted) The request has been accepted
+================ ===============================
+
+
+DELETE
+""""""
+
+No request parameters/headers.
+
+No reply content/headers.
+
+================ ===============================
+Return Code Description
+================ ===============================
+204 (No Content) The request succeeded
+409 (Conflict) The container is not empty
+================ ===============================
+
+
+Object Level
+^^^^^^^^^^^^
+
+List of operations:
+
+========= =================================
+Operation Description
+========= =================================
+HEAD Retrieve object metadata
+GET Read object data
+PUT Write object data or copy/move object
+COPY Copy object
+MOVE Move object
+POST Update object metadata
+DELETE Delete object
+========= =================================
+
+
+HEAD
+""""
+
+No request parameters/headers.
+
+========================== ===============================
+Reply Header Name Value
+========================== ===============================
+ETag The MD5 hash of the object
+Content-Length The size of the object
+Content-Type The MIME content type of the object
+Last-Modified The last object modification date
+Content-Encoding The encoding of the object (optional)
+Content-Disposition The presentation style of the object (optional)
+X-Object-Manifest Large object support (optional)
+X-Object-Meta-* Optional user defined metadata
+========================== ===============================
+
+|
+
+================ ===============================
+Return Code Description
+================ ===============================
+204 (No Content) The request succeeded
+================ ===============================
+
+
+GET
+"""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+Range Optional range of data to retrieve
+If-Match Retrieve if ETags match
+If-None-Match Retrieve if ETags don't match
+If-Modified-Since Retrieve if object has changed since provided timestamp
+If-Unmodified-Since Retrieve if object has not changed since provided timestamp
+==================== ================================
+
+The reply is the object's data (or part of it). Object headers (as in a ``HEAD`` request) will also be included.
+
+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.
+
+========================== ===============================
+Reply Header Name Value
+========================== ===============================
+ETag The MD5 hash of the object
+Content-Length The size of the data returned
+Content-Type The MIME content type of the object
+Content-Range The range of data included (only on a single range request)
+Last-Modified The last object modification date
+Content-Encoding The encoding of the object (optional)
+Content-Disposition The presentation style of the object (optional)
+X-Object-Manifest Large object support (optional)
+X-Object-Meta-* Optional user defined metadata
+========================== ===============================
+
+|
+
+=========================== ==============================
+Return Code Description
+=========================== ==============================
+200 (OK) The request succeeded
+206 (Partial Content) The range request succeeded
+304 (Not Modified) The object has not been modified
+412 (Precondition Failed) The condition set can not be satisfied
+416 (Range Not Satisfiable) The requested range is out of limits
+=========================== ==============================
+
+
+PUT
+"""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+ETag The MD5 hash of the object (optional to check written data)
+Content-Length The size of the data written
+Content-Type The MIME content type of the object
+Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored)
+X-Copy-From The source path in the form ``/<container>/<object>``
+X-Move-From The source path in the form ``/<container>/<object>``
+Content-Encoding The encoding of the object (optional)
+Content-Disposition The presentation style of the object (optional)
+X-Object-Manifest Large object support (optional)
+X-Object-Meta-* Optional user defined metadata
+==================== ================================
+
+|
+
+========================== ===============================
+Reply Header Name Value
+========================== ===============================
+ETag The MD5 hash of the object (on create)
+========================== ===============================
+
+|
+
+=========================== ==============================
+Return Code Description
+=========================== ==============================
+201 (Created) The object has been created
+411 (Length Required) Missing ``Content-Length`` or ``Content-Type`` in the request
+422 (Unprocessable Entity) The MD5 checksum of the data written to the storage system does not match the (optionally) supplied ETag value
+=========================== ==============================
+
+
+COPY
+""""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+Destination The destination path in the form ``/<container>/<object>``
+Content-Type The MIME content type of the object (optional)
+Content-Encoding The encoding of the object (optional)
+Content-Disposition The presentation style of the object (optional)
+X-Object-Manifest Large object support (optional)
+X-Object-Meta-* Optional user defined metadata
+==================== ================================
+
+No reply content/headers.
+
+=========================== ==============================
+Return Code Description
+=========================== ==============================
+201 (Created) The object has been created
+=========================== ==============================
+
+
+MOVE
+""""
+
+Same as ``COPY``.
+
+
+POST
+""""
+
+==================== ================================
+Request Header Name Value
+==================== ================================
+Content-Encoding The encoding of the object (optional)
+Content-Disposition The presentation style of the object (optional)
+X-Object-Manifest Large object support (optional)
+X-Object-Meta-* Optional user defined metadata
+==================== ================================
+
+No reply content/headers.
+
+The allowed headers are considered to be user defined metadata. The update operation will overwrite all previous values and remove any keys not supplied.
+
+=========================== ==============================
+Return Code Description
+=========================== ==============================
+202 (Accepted) The request has been accepted
+=========================== ==============================
+
+
+DELETE
+""""""
+
+No request parameters/headers.
+
+No reply content/headers.
+
+=========================== ==============================
+Return Code Description
+=========================== ==============================
+204 (No Content) The request succeeded
+=========================== ==============================
+
+
+Summary
+^^^^^^^
+
+List of differences from the OOS API:
+
+* Support for ``X-Account-Meta-*`` style headers at the account level. Use ``POST`` to update.
+* Support for ``X-Container-Meta-*`` style headers at the account level. Can be set when creating via ``PUT``. Use ``POST`` to update.
+* Header ``X-Container-Object-Meta`` at the container level and parameter ``meta`` in container listings.
+* All metadata replies, at all levels, include latest modification information.
+* At all levels, a ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers.
+* 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.
+* Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``. These are all replaced with every update operation.
+* Multi-range object GET support as outlined in RFC2616.
+* Object ``MOVE`` support.
+
+Clarifications/suggestions:
+
+* 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.
+* 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.
+* A ``GET`` reply for a level will include all headers of the corresponding ``HEAD`` request.
+* 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.
+* The ``Accept`` header may be used in requests instead of the ``format`` parameter to specify the desired reply format. The parameter overrides the header.
+* Container/object lists use a ``200`` return code if the reply is of type json/xml. The reply will include an empty json/xml.
+* In headers, dates are formatted according to RFC 1123. In extended information listings, dates are formatted according to ISO 8601.
+* While ``X-Object-Manifest`` can be set and unset, large object support is not yet implemented (**TBD**).
+
+The Pithos Client
+-----------------
+
+User Experience
+^^^^^^^^^^^^^^^
+
+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.
+
+Upon entrance to the service, a user is presented with the following elements - which can be represented as folders or with other related icons:
+
+* 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.
+* The ``trash`` element, which contains files that have been marked for deletion, but can still be recovered.
+* The ``shared`` element, which contains all objects shared by the user to other users of the system.
+* The ``others`` element, which contains all objects that other users share with the user.
+* 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.).
+* 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.
+
+Objects in Pithos can be:
+
+* Assigned custom tags.
+* Moved to trash and then deleted.
+* Shared with specific permissions.
+* Made public (shared with non-Pithos users).
+* Set to monitor changes via version tracking.
+
+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.
+
+Conventions and Metadata Specification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pithos clients should use the ``pithos`` container for all Pithos objects. Object names use the ``/`` delimiter to impose a hierarchy of folders and files.
+
+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 (except ``trash``) 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.
+
+To manage the deletion of files use the same API and the ``X-Object-Meta-Trash`` key. The string ``trash`` can not be used as a tag. The ``trash`` element should be presented as a folder, although with no hierarchy.
+
+The metadata specification is summarized in the following table.
+
+=========================== ==============================
+Metadata Name Value
+=========================== ==============================
+X-Object-Meta-Trash Set to ``true`` if the object has been moved to the trash
+X-Object-Meta-* Use for other tags that apply to the object
+=========================== ==============================
projects / pithos / commitdiff