CDMI RESTful API

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:

Response Status:

HTTP Status Description
201 Created The new collection was created
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-container" Optional
Content-Type Header String "application/cdmi-container" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Request Body:

Field Name Type Description Requirement
metadata JSON Object Metadata for the collection object Optional

Response Headers:

Header Type Description Requirement
Content-Type Header String "application/cdmi-container" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Body:

Field Name Type Description Requirement
objectType JSON String "application/cdmi-container" Mandatory
objectID JSON String ObjectID of the object Mandatory
objectName JSON String Name of the object Mandatory
parentURI JSON String URI for the parent object Mandatory
parentID JSON String Object ID of the parent object Mandatory
metadata JSON Object Metadata for the object Optional

Response Status:

HTTP Status Description
201 Created The new collection was created
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Response Status:

HTTP Status Description
204 No Content The collection was deleted
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Status:

HTTP Status Description
204 No Content The collection was deleted
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-container" Optional
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Body:

Field Name Type Description Requirement
objectType JSON String "application/cdmi-container" Mandatory
objectID JSON String ObjectID of the object Mandatory
objectName JSON String Name of the object Mandatory
parentURI JSON String URI for the parent object Mandatory
parentID JSON String Object ID of the parent object Mandatory
metadata JSON Object Metadata for the object Optional
children JSON Array of JSON Strings Name of the children objects in the collection object. Mandatory

Response Status:

HTTP Status Description
200 OK The metadata for the collection is provided in the Body
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-container" Optional
X-CDMI-Specification-Version Header String "1.1" Mandatory

Request Body:

Field Name Type Description Requirement
metadata JSON Object Metadata for the collection object Optional

Response Status:

HTTP Status Description
204 No Content The collection content was updated
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Content-Type Header String The content type of the data to be stored as a data object Optional
Content-Range Header String A valid range-specifier Optional

Request Body:

The request Body contains the data to be stored.

Response Status:

HTTP Status Description
201 Created The new data object was created
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-object" Optional
Content-Type Header String "application/cdmi-object" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Request Body:

Field Name Type Description Requirement
mimetype JSON String Mime type of the data contained within the value field Optional
metadata JSON Object Metadata for the collection object Optional
value JSON String The data object value Optional

Response Headers:

Header Type Description Requirement
Content-Type Header String "application/cdmi-object" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Body:

Field Name Type Description Requirement
objectType JSON String "application/cdmi-container" Mandatory
objectID JSON String ObjectID of the object Mandatory
objectName JSON String Name of the object Mandatory
parentURI JSON String URI for the parent object Mandatory
parentID JSON String Object ID of the parent object Mandatory
mimetype JSON String Mime type of the value of the data object Optional
metadata JSON Object Metadata for the object Optional

Response Status:

HTTP Status Description
201 Created The new data object was created
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Response Status:

HTTP Status Description
204 No Content The data object was deleted
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Status:

HTTP Status Description
204 No Content The collection was deleted
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Range Header String A valid range specifier Optional

Response Headers:

Header Type Description Requirement
Content-Type Header String The mimetype of the data object Mandatory

Response Body:

The response Body is the content of the data object.

Response Status:

HTTP Status Description
200 OK The data object content was returned in the response
206 Partial Content The data object content was returned in the response
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-object" Optional
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Headers:

Header Type Description Requirement
Content-Type Header String "application/cdmi-object" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Response Body:

Field Name Type Description Requirement
objectType JSON String "application/cdmi-object" Mandatory
objectID JSON String ObjectID of the object Mandatory
objectName JSON String Name of the object Mandatory
parentURI JSON String URI for the parent object Mandatory
parentID JSON String Object ID of the parent object Mandatory
mimetype JSON String MIME type of the value of the data object Mandatory
metadata JSON Object Metadata for the object Mandatory
value JSON String data object value Conditional

Response Status:

HTTP Status Description
200 OK The metadata for the collection is provided in the Body
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Content-Type Header String The content type of the data to be stored as a data object Optional
Content-Range Header String A valid range-specifier Optional

Request Body:

The request Body contains the data to be stored.

Response Status:

HTTP Status Description
201 No Content The new data object was updated
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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:

Request Headers:

Header Type Description Requirement
Accept Header String "application/cdmi-object" Mandatory
X-CDMI-Specification-Version Header String "1.1" Mandatory

Request Body:

Field Name Type Description Requirement
mimetype JSON String Mime type of the data contained within the value field Optional
metadata JSON Object Metadata for the collection object Optional
value JSON String The data object value Optional

Response Status:

HTTP Status Description
204 No Content The data object content was updated
400 Bad Request The request contains invalid parameters
401 Unauthorized The authentication credentials are missing or invalid
403 Forbidden The client lacks the proper authorization
404 Not Found The resource was not found at the specified URI

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