We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Object Storage Open RESTful API Specification (CDMI) - FIWARE Forge Wiki

Object Storage Open RESTful API Specification (CDMI)

From FIWARE Forge Wiki

(Difference between revisions)
Jump to: navigation, search
(Introduction to the Cloud Data Management Interface (CDMI) API)
Line 10: Line 10:
= Introduction to the Cloud Data Management Interface (CDMI) API =
= Introduction to the Cloud Data Management Interface (CDMI) API =
 +
Please check the following [[FI-WARE Open Specification Legal Notice (essential patents license) | Legal Notice (essential patents license)]] to understand the rights to use these specifications.
 +
This specification is based on [http://cdmi.sniacloud.com/ CDMI] published by [http://www.snia.org/tech_activities/work/twgs SNIA Cloud Storage TWG]. Please, refer to [http://www.snia.org/about/corporate_info/ip_policy SNIA IP Policy] to understand the relevant usage rights.
This specification is based on [http://cdmi.sniacloud.com/ CDMI] published by [http://www.snia.org/tech_activities/work/twgs SNIA Cloud Storage TWG]. Please, refer to [http://www.snia.org/about/corporate_info/ip_policy SNIA IP Policy] to understand the relevant usage rights.

Revision as of 07:36, 13 August 2014

Contents


Intended Audience

This specification is intended for both software developers and reimplementors of this API. For the former, this document provides a full specification of how to interoperate with Object Storage Platforms that implement the CDMI API. For the latter, this specification indicates the interface to be provided to allow clients interoperate with the Object Storage Platform. To use this information, the reader should firstly have a general understanding of the Object Storage Generic Enabler service. You should also be familiar with:

  • RESTful web services.
  • HTTP 1.1.
  • JSON data serialisation formats.

Introduction to the Cloud Data Management Interface (CDMI) API

Please check the following Legal Notice (essential patents license) to understand the rights to use these specifications.

This specification is based on CDMI published by SNIA Cloud Storage TWG. Please, refer to SNIA IP Policy to understand the relevant usage rights.

CDMI API Core

At the core of CDMI are the basic management operations of Create, Retrieve, Update and Delete. The key CDMI entities that one can possibly interact with through CDMI are:

  • Capabilities: allows a client to discover features of the CDMI standard is implemented by a provider. This is required for basic CDMI compliance.
  • Object: opaque piece of data with associated meta-data. This is required for basic CDMI compliance. This CDMI entity will allow for the representation of Object.
  • Container: collection of objects with associated meta-data. This is required for basic CDMI compliance. This CDMI entity will allow for the representation of Container and Account.
  • Domain: represent the concept of administrative ownership of stored data within a CDMI storage system. This is an optional entity and is not required to be implemented for basic CDMI compliance. For the first release of the Object Storage GE this feature will not be supported.
  • Queue: is a first-in, first-out (FIFO) access when storing and retrieving data. This is an optional entity and is not required to be implemented for basic CDMI compliance. For the first release of the Object Storage GE this feature will not be supported.

More information on these entities can be found in Sections 12, 8, 9, 10 and 11 respectively in the CDMI specification

API Change History

This version of the Object Storage Open RESTful API Specification replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 30, 2012
  • Initial Version
Sept 4, 2012
  • Updated Templated sections
April 29, 2013
  • Restructured content and updated API Operations and implementation details

How to Read This Document

It is assumed that the reader is familiar with the RESTful architectural style. This document uses the following notation:

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.

For a description of some terms used along this document, see the Object Storage Architecture.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Summary_of_FI-WARE_Open_Specifications. For more details about the Cloud hosting architecture in which this Generic Enabler fits, please refer to high level cloud hosting architecture description. Related documents, including an introduction to the overall FI-WARE architecture, are available at the same site.

General CDMI API Information

Resources Summary

Graphically the main CDMI entities as listed above are related to each other as is shown in the image below.

For the purposes of data storage a CDMI Client only needs to know about container and data objects. CDMI functionality is exposed via a RESTful API that:

  • Enables clients to discover capabilities of the object storage offering
  • Manage containers and the objects that are placed within them
  • Assigns and manipulates metadata to containers and objects

Meta-data is core to enabling richer management of data within CDMI. Meta-data can be associated with both system-managed objects and of course user-managed objects. Indeed, according to the specification “metadata is interpreted by the cloud offering as data requirements that control the operation of underlying data services for that data.” This focus of CDMI makes it as a very flexible and suitable specification for the Object Storage GE, especially as providing quality of service and experience is a core focus in FI-ware. It is through CDMI’s meta-data facilities that various data handling policies and QoS parameters can be specified and how the abstract entity of Policy can be represented.

Authentication

Each HTTP request against the OCCI requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) as such mechanisms are orthogonal to the API. This will be determined by the specific provider that implements the GE. Please contact it to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS). See Section 5.12 and Annex A in the CDMI specification for more information.

Representation Format

The CDMI API represents its model in the JSON format. The CDMI specification details this further through examples.

Representation Transport

Resource representation is transmitted between clients and servers by using the HTTP 1.1 protocol, as defined by IETF RFC–2616. Each time a HTTP request contains payload, a Content-Type header is used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

Resource identification in CDMI is achieved using the defined Object ID that is detailed in Section 5.10 and 5.11

Versions

The CDMI specification uses the X-CDMI-Specification-Version header to relay the supported version of the CDMI implementation.

Faults

See the CDMI Specification Section 7 for details on Status Codes and Faults.

API Operations

Please refer to the CDMI specification for definitive details of all CDMI API operations and comprehensive examples. There are specific document sections dedicated to each CDMI object as listed below.

Rather than duplicate documentation of the CDMI standard, a summary of some of the key CDMI operations is presented below.

discoverCapabilities

Allows the technical capabilities and installed features of a CDMI deployment to be discovered at runtime.

Verb URI Description
GET /cdmi_capabilities/ Returns details of capabilities of the CDMI installation.

Normal Response Code(s): OK (200)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), notAcceptable(406) Example discoverCapabilitiesResponse:

HTTP/1.1 200 OK
Content-Type: application/cdmi-capability
X-CDMI-Specification-Version: 1.0.1
{
"objectType" : "application/cdmi-capability",
"objectID" : "00007E7F0010CEC234AD9E3EBFE9531D",
"objectName" : "cdmi_capabilities/",
"parentURI" : "/",
"parentID" : "00007E7F0010DCECC805FB6D195DDBCB",
"capabilities" : {
"cdmi_domains" : "true",
"cdmi_queues" : "true",
"cdmi_query" : "true",
"cdmi_metadata_maxsize" : "4096",
"cdmi_metadata_maxitems" : "1024",
"cdmi_size" : "true",
"cdmi_list_children" : "true",
    },
...
}

createContainer

Creates a container in which other containers and objects can be stored.

Verb URI Description
PUT /{container name}/ Creates a container named {container name}.

Normal Response Code(s): created (201), accepted (202)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), conflict (409)

Example createContainer response:

HTTP/1.1 201 Created
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.0.1
{
"objectType" : "application/cdmi-container",
"objectID" : "00007E7F00102E230ED82694DAA975D2",
"objectName" : "MyContainer/",
"parentURI" : "/",
"parentID" : "00007E7F0010128E42D87EE34F5A6560",
"domainURI" : "/cdmi_domains/MyDomain/",
"capabilitiesURI" : "/cdmi_capabilities/container/",
"completionStatus" : "Complete",
"metadata" : {
    "cdmi_size" : "0"
    },
"childrenrange" : "",
"children" : [
]
}   

createObject

Stores a binary object in the specified location.

Verb URI Description
PUT /{container name}/{object name} Creates an object named {object name} in the container named {container name}. The content of the object is supplied in the request body.

Normal Response Code(s): created (201), accepted (202)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), conflict (409)

Example createObject Request:

PUT /MyContainer/MyDataObject.txt HTTP/1.1
Host: cloud.example.com
Accept: application/cdmi-object
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.0.1
{
    "mimetype" : "text/plain",
    "metadata" : {
    },
    "value" : "Hello CDMI World!"
}   

Example createObject Response:

HTTP/1.1 201 Created
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.0.1
{
"objectType" : "application/cdmi-object",
"objectID" : "00007E7F0010BD1CB8FF1823CF05BEE4",
"objectName" : "MyDataObject.txt",
"parentURI" : "/MyContainer/",
"parentID" : "00007E7F00102E230ED82694DAA975D2",
"domainURI" : "/cdmi_domains/MyDomain/",
"capabilitiesURI" : "/cdmi_capabilities/dataobject/",
"completionStatus" : "Complete",
"mimetype" : "text/plain",
"metadata" : {
    "cdmi_size" : "17"
    }
}   

listContainerContents

Returns a list of the contents of a container.

Verb URI Description
GET /{container name}/ Lists the contents of the container named {container name}.

Normal Response Code(s): created (201), found (302)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), notAcceptable (406)

Example listContainerContents Response:

HTTP/1.1 200 OK
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.0.1
{
"objectType" : "application/cdmi-container",
"objectID" : "00007E7F00102E230ED82694DAA975D2",
"objectName" : "MyContainer/",
"parentURI" : "/",
"parentID" : "00007E7F0010128E42D87EE34F5A6560",
"domainURI" : "/cdmi_domains/MyDomain/",
"capabilitiesURI" : "/cdmi_capabilities/container/",
"completionStatus" : "Complete",
"metadata" : {
    "cdmi_size" : "83"
    },
"childrenrange" : "0-0",
"children" : [
    "MyDataObject.txt"
    ]
}   

readObjectContents

Retrieves a specified object from the storage system.

Verb URI Description
GET /{container name}/{object name} Returns the contents of the object named {object name} in the container named {container name}. The contents are returned in the response body.

Normal Response Code(s): ok (200), accepted (202), found (302)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), notAcceptable (406)

Example readObjectContents Response:

HTTP/1.1 200 OK
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.0.1
{
"objectType": "application/cdmi-object",
"objectID": "00007E7F0010BD1CB8FF1823CF05BEE4",
"objectName": "MyDataObject.txt",
"parentURI": "/MyContainer/",
"parentID" : "00007E7F00102E230ED82694DAA975D2",
"domainURI": "/cdmi_domains/MyDomain/",
"capabilitiesURI": "/cdmi_capabilities/dataobject/",
"completionStatus": "Complete",
"mimetype": "text/plain",
"metadata": { "cdmi_size": "17"
},
"valuetransferencoding": "utf-8",
"valuerange": "0-16",
"value": "Hello CDMI World!“
}

deleteObject

Deletes a specified object from the storage system.

Verb URI Description
DELETE /{container name}/{object name} Deletes the object named {object name} in the container named {container name}.

Normal Response Code(s): noContent (204)

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), notFound(404), conflict (409)

Example deleteObject Response:

HTTP/1.1 204 No Content

Implementation Specific Caveats

The current CDMI implementation for OpenStack Swift offered by FI-WARE implements all basic elements of the CDMI interface. At the time of writing, capabilities, container and object object types are all supported. Containers can be nested and the retrieval of a limited sub-section of an object is also supported.

Personal tools
Create a book