CDMI RESTful API

• CDMI RESTful API
  • Presentation
  • Cloud Data Management Interface
  • Collections
    • Create a collection using HTTP
    • Create a collection using CDMI
    • Delete a collection using HTTP
    • Delete a collection using CDMI
    • Read a collection using CDMI
    • Update a collection using CDMI
  • Data Objects
    • Create a data object using HTTP
    • Create a data object using CDMI
    • Delete a data object using HTTP
    • Delete a data object using CDMI
    • Read a data object using HTTP
    • Read a data object using CDMI
    • Update a data object using HTTP
    • Update a data object using CDMI

Presentation

The Indigo Web project is a translation layer that provides an accessible and well structured set of access methods to the data management system. Access methods comes in the form of RESTful services, accessible via the base url of an indigo node running indigo-web. The object store is used to store and register digital objects in the cluster. The data model is that of a hierarchical object store, i.e. objects are chunks of data that are stored in selected containers and may have associated metadata in the form of name/value pairs. The repository is agnostic to the data and metadata it stores, and the interpretation of both is the responsibility of the various applications, interpreters and engines that use the store. The object store provides a CDMI implementation for HTTP access to digital objects in the registry. The CDMI standard is fairly well designed, and the richest of the available “standards”. We layer a CDMI interface to provide remote (https) based access to the objects and metadata.

Cloud Data Management Interface

The object store can be used to organize collections and digital objects in the store. It implements the Cloud Data Management Interface (CDMI) that defines the functional interface that applications may use to create, retrieve, update and delete data elements from the Object Store (CRUD operations). In addition, metadata can be set on collections and their contained data elements through this interface. The CDMI web service is accessible at /api/cdmi from you root URI.

Collections

Create a collection using HTTP

Synopsys:

To create a new collection object, the following request shall be performed:

PUT <root URI>/api/cdmi/<CollectionName>/<NewCollectionName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection that already exist, with one ‘/’ between each pair of collection names.
• <NewCollectionName> is the name for the collection to be created.

Response Status:

Example:

PUT to the collection URI to create a collection:

PUT /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12

Response:

HTTP/1.1 201 Created

Create a collection using CDMI

Synopsys:

To create a new collection object, the following request shall be performed:

PUT <root URI>/api/cdmi/<CollectionName>/<NewCollectionName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection that already exist, with one ‘/’ between each pair of collection names.
• <NewCollectionName> is the name for the collection to be created.

Request Headers:

Request Body:

Response Headers:

Response Body:

Response Status:

Example:

PUT to the URI the collection object name and metadata:

PUT /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12
Accept: application/cdmi-container
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.1

{
  “metadata”: {}
}

Response:

HTTP/1.1 201 Created
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.1

{
  "objectType" : "application/cdmi-container",
  "objectID" : "00007ED900104E1D14771DC67C27BF8B",
  "objectName" : "MyCollection/",  
  "parentURI" : "/",
  "parentID" : "00007E7F0010128E42D87EE34F5A6560",
  "metadata" : {
                ...
               },
}

Delete a collection using HTTP

Synopsys:

To delete an existing container object, including all contained children, the following request shall be performed:

DELETE <root URI>/api/cdmi/<CollectionName>/<TheCollectionName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <TheCollectionName> is the name for the collection to be deleted.

Response Status:

Example:

DELETE to the collection URI:

DELETE /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12

Response:

HTTP/1.1 204 No Content

Delete a collection using CDMI

Synopsys:

To delete an existing container object, including all contained children, the following request shall be performed:

DELETE <root URI>/api/cdmi/<CollectionName>/<NewCollectionName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection names.
• <TheCollectionName> is the name for the collection to be deleted.

Request Headers:

Response Status:

Example:

DELETE the collection at URI:

DELETE /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12
X-CDMI-Specification-Version: 1.1

Response:

HTTP/1.1 204 No Content

Read a collection using CDMI

Synopsys:

To read all fields from an existing collection object, the following request shall be performed:

GET <root URI>/api/cdmi/<CollectionName>/<TheCollectionName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <TheCollectionName> is the name specified for the collection object to be read from.

Request Headers:

Response Body:

Response Status:

Example:

GET to the collection object URI to read all the fields of the collection object:

GET /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12
Accept: application/cdmi-container
X-CDMI-Specification-Version: 1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.1

{
  "objectType" : "application/cdmi-container",
  "objectID" : "00007ED900104E1D14771DC67C27BF8B",
  "objectName" : "MyCollection/",  
  "parentURI" : "/",
  "parentID" : "00007E7F0010128E42D87EE34F5A6560",
  "metadata" : {
                ...
               },
  "children" : [
               "child1",
               “child2”,
               …
               ]
}

Update a collection using CDMI

Synopsys:

To update some or all fields in an existing collection object, the following request shall be performed:

PUT <root URI>/api/cdmi/<CollectionName>/<TheCollectionName>/

To add, update, and remove specific metadata items of an existing collection object, the following request shall be performed:

PUT <root URI>/api/cdmi/<CollectionName>/<TheCollectionName>/?metadata:<metadataname>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collectionobjects.
• <TheCollectionName> is the name for the collection to be updated.

Request Headers:

Request Body:

Response Status:

Example:

PUT to the URI the collection object to set new metadata:

PUT /api/cdmi/MyCollection/ HTTP/1.1
Host: 192.168.12.12
Content-Type: application/cdmi-container
X-CDMI-Specification-Version: 1.1

{
  “metadata”: {}
}

Response:

HTTP/1.1 204 No Content

Data Objects

Create a data object using HTTP

Synopsys:

The following HTTP PUT creates a new data object at the specified URI:

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection that already exist.
• <DataObjectName> is the name for the data object to be created.

Request Headers:

Request Body:

The request Body contains the data to be stored.

Response Status:

Example:

PUT to the collection URI the data object name and contents:

PUT /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Content-Type: text/plain;charset=utf-8
Content-Length: 37

This is the Value of this Data Object

Response:

HTTP/1.1 201 Created

Create a data object using CDMI

Synopsys:

To create a new data object, the following request shall be performed:

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>/

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection that already exist, with one ‘/’ between each pair of collection names.
• <DataObjectName> is the name for the data object to be created.

Request Headers:

Request Body:

Response Headers:

Response Body:

Response Status:

Example:

PUT to the collection URI the data object name and contents:

PUT /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Accept: application/cdmi-object
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.1

{
  "mimetype" : "text/plain",
  "metadata": {...},
  "value" : "This is the Value of this Data Object"
}

Response:

HTTP/1.1 201 Created
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.1

{
  "objectType" : "application/cdmi-container",
  "objectID" : "00007ED90010D891022876A8DE0BC0FD",
  "objectName" : "MyDataObject.txt",  
  "parentURI" : "/MyContainer/",
  "parentID" : "00007E7F00102E230ED82694DAA975D2",
  "mimetype" : "text/plain",
  "metadata" : {
                "cdmi_size" : "37"
               },
}

Delete a data object using HTTP

Synopsys:

The following HTTP DELETE deletes an existing data object at the specified URI:

DELETE <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <DataObjectName> is the name of the data object to be deleted.

Response Status:

Example:

DELETE to the data object URI:

DELETE /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12

Response:

HTTP/1.1 204 No Content

Delete a data object using CDMI

Synopsys:

The following HTTP DELETE deletes an existing data object at the specified URI:

DELETE <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection names.
• <DataObjectName> is the name of the data object to be deleted.

Request Headers:

Response Status:

Example:

DELETE the data object at URI:

DELETE /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
X-CDMI-Specification-Version: 1.1

Response:

HTTP/1.1 204 No Content

Read a data object using HTTP

Synopsys:

The following HTTP GET reads from an existing data object at the specified URI:

GET <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <DataObjectName> is the name specified of the data object to be read from.

Request Headers:

Response Headers:

Response Body:

The response Body is the content of the data object.

Response Status:

Example 1:

GET to the data object URI to read the value of the data object:

GET /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 37

This is the Value of this Data Object

Example 2:

GET to the data object URI to read the first 11 bytes of the value of the data object:

GET /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Range: bytes=0-10

Response:

HTTP/1.1 206 Partial Content
Content-Type: text/plain
Content-Range: bytes 0-10/37
Content-Length: 11

This is the

Read a data object using CDMI

Synopsys:

The following HTTP GET reads from an existing data object at the specified URI:

GET <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

GET <root URI>/api/cdmi/<CollectionName>/<DataObjectName>?value:<range>;...

GET <root URI>/api/cdmi/<CollectionName>/<DataObjectName>?metadata:<prefix>;...

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <DataObjectName> is the name specified for the data object to be read from.
• <range> is a byte range of the data object value to be returned in the value field.
• <prefix> is a matching prefix that returns all metadata items that start with the prefix value.

Request Headers:

Response Headers:

Response Body:

Response Status:

Example:

GET to the data object URI to read all fields of the data object:

GET /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Accept: application/cdmi-object
X-CDMI-Specification-Version: 1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.1

{
  "objectType" : "application/cdmi-object",
  "objectID" : "00007ED90010D891022876A8DE0BC0FD",
  "objectName" : "MyDataObject.txt",  
  "parentURI" : "MyCollection/",
  "parentID" : "00007E7F00102E230ED82694DAA975D2",
  "mimetype" : "text/plain",
  "metadata" : {
                "cdmi_size" : "37"
               },
  "valuerange" : "0-36",
  "value" : "This is the Value of this Data Object"

}

Update a data object using HTTP

Synopsys:

The following HTTP PUT updates an existing data object at the specified URI:

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection that already exist.
• <DataObjectName> is the name for the data object to be updated.

Request Headers:

Request Body:

The request Body contains the data to be stored.

Response Status:

Example:

PUT to the data object URI to update the value of the data object:

PUT /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Content-Type: text/plain
Content-Length: 37

This is the value of this Data Object

Response:

HTTP/1.1 204 No Content

Update a data object using CDMI

Synopsys:

The following HTTP PUT updates an existing data object at the specified URI:

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>/

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>/?value:<range>

PUT <root URI>/api/cdmi/<CollectionName>/<DataObjectName>/?metadata:<metadataname>

where:

• <root URI> is the URL of the web server.
• <CollectionName> is zero or more intermediate collection objects.
• <DataObjectName> is the name for the data object to be updated.
• <range> is a byte range for the data object value to be updated.
• <metadataname> is the name for the metadata to be updated.

Request Headers:

Request Body:

Response Status:

Example:

PUT to the data object URI to set new field values:

PUT /api/cdmi/MyCollection/MyDataObject.txt HTTP/1.1
Host: 192.168.12.12
Content-Type: application/cdmi-object
X-CDMI-Specification-Version: 1.1

{
  "mimetype" : "text/plain",
  "metadata": { "colour": "red", },
  "value" : "This is the Value of this Data Object"
}

Response:

HTTP/1.1 204 No Content