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.
Overview
--------
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.
Pithos+ 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.
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.
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.
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
* 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.
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 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.
Whatever marked as to be determined (**TBD**), should not be considered by
implementors.
More info about Pithos can be found here: https://code.grnet.gr/projects/pithos
Document Revisions
^^^^^^^^^^^^^^^^^^
...
...
@@ -93,24 +81,14 @@ Revision Description
0.1 (May 17, 2011) Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011).
In Pithos+, each user is uniquely identified by a token. All API requests
require a token and each token is internally resolved to an account string. The
API uses the account string to identify the user's own files, thus whether a
request is local or cross-account.
In Pithos, each user is uniquely identified by a token. All API requests require a token and each token is internally resolved to an account string. The API uses the account string to identify the user's own files, thus whether a request is local or cross-account.
Pithos+ does not keep a user database. For development and testing purposes,
user identifiers and their corresponding tokens can be defined in the settings
file. However, Pithos is designed with an external authentication service in
mind. This service must handle the details of validating user credentials and
communicate with Pithos via a middleware software component that, given a
token, fills in the internal request account variable.
Pithos does not keep a user database. For development and testing purposes, user identifiers and their corresponding tokens can be defined in the settings file. However, Pithos is designed with an external authentication service in mind. This service must handle the details of validating user credentials and communicate with Pithos via a middleware software component that, given a token, fills in the internal request account variable.
Client software using Pithos+, if not already knowing a user's identifier and
token, should forward to the ``/login`` URI. The Pithos server, depending on
its configuration will redirect to the appropriate login page.
Client software using Pithos, if not already knowing a user's identifier and token, should forward to the ``/login`` URI. The Pithos server, depending on its configuration will redirect to the appropriate login page.
The login URI accepts the following parameters:
...
...
@@ -126,10 +104,10 @@ When done with logging in, the service's login URI should redirect to the URI pr
A user management service that implements a login URI according to these conventions is Astakos (https://code.grnet.gr/projects/astakos), by GRNET.
API Operations
The Pithos API
--------------
The URI requests supported by the Pithos+ API follow one of the following forms:
The URI requests supported by the Pithos API follow one of the following forms:
* 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.
* A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers.
* 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.
Recommended Practices and Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Assuming an authentication token is obtained, the following high-level operations are available - shown with ``curl``:
