API Walkthrough

Introduction

This walk-through explains the basic functionality of the CDMI server. It demonstrates the data path and the QoS path to create and modify CDMI containers and data objects via the CDMI server's RESTful interface.

All API REST calls need either HTTP Basic authentication (see Configuration section) or OpenId Connect authentication. For OpenId Connect please have a look at the INDIGO-DataCloud OpenId Connect provider IAM.

The API follows the SNIA CDMI specification in its current version (1.1.0). A detailed overview of the specification can be found at SNIA CDMI.

This guide focuses on the QoS management via CDMI, for an overview of the full CDMI functionality please have a look at the SNIA specification.

This walkthrough makes use of the curl command line tool to perform the HTTP calls, but any other tool should work as well.

Querying the CDMI root /

Basic querying can be performed at the root CDMI endpoint. Any path starting from the CDMI root can be queried and will return the CDMI specific meta-data for the queried object if an equivalent object (depending on the storage back-end module) exists.

GET /

An example call might look like the following.

curl -u restadmin:restadmin -H "X-CDMI-Specification-Version: 1.1" http://localhost/

The reponse in this case will be the CDMI specific meta-data of the root container object. For a different path, all the returned information will be provided by the specific storage back-end module if an equivalent object exists. For example querying for /myData will make the CDMI server to interact with the configured storage back-end module to retrieve information about the /myData equivalent object on the storage back-end. This equivalent object can be for example a file, directory, container or any other object, dependend on the configured storage back-end.

Querying the CDMI capabilities /cdmi_capabilities

The /cdmi_capabilities endpoint provides an overview of the CDMI server capabilities and also the capabilities of the different objects. Capabilities are a set of attributes that provide information about the storage system and object specific qualities. To explore the capabilities of the CDMI server one would look at the root capabilities object and move further down the path as returned.

GET /cdmi_capabilities

An example call might look like the following.

curl -u restadmin:restadmin -H "X-CDMI-Specification-Version: 1.1" -H "Content-Type: application/cdmi-capability" http://localhost/cdmi_capabilities

An example response might look like the following.

{
    "capabilities": {},
    "children": [
        "container",
        "dataobject"
    ],
    "childrenrange": "0-1",
    "metadata": {},
    "objectID": "0001869F0018CFB031613763613636302D393032302D3432",
    "objectName": "cdmi_capabilities",
    "objectType": "application/cdmi-capability",
    "parentID": "0001869F0018D89139336634313462632D386538372D3464",
    "parentURI": "/"
}

From here you can explore more of the CDMI server capabilities by moving down the path as indicated with the children field in the response, e.g.

curl -u restadmin:restadmin -H "X-CDMI-Specification-Version: 1.1" -H "Content-Type: application/cdmi-capability" http://localhost/cdmi_capabilities/dataobject

At some point you end up with a concret set of attributes describing dataobject or container qualities, e.g.

curl -u restadmin:restadmin -H "X-CDMI-Specification-Version: 1.1" -H "Content-Type: application/cdmi-capability" http://localhost/cdmi_capabilities/dataobject/profile1

{
    "capabilities": {
        "cdmi_capabilities_allowed": "/cdmi_capabilities/dataobject/profile1 /cdmi_capabilities/dataobject/profile2",
        "cdmi_capabilities_exact_inherit": true,
        "cdmi_capabilities_templates": true,
        "cdmi_data_redundancy": true,
        "cdmi_geographic_placement": true,
        "cdmi_latency": true
    },
    "metadata": {
        "cdmi_data_redundancy": 4,
        "cdmi_geographic_placement": [
            "DE",
            "FR"
        ],
        "cdmi_latency": 100
    },
    "objectID": "0001869F0018764532653238323630362D326639342D3431",
    "objectName": "profile1",
    "objectType": "application/cdmi-capability",
    "parentID": "0001869F001803C539633837366133612D613231302D3433",
    "parentURI": "cdmi_capabilities/dataobject"
}

The URL for that specific set of capabilities is important to manage QoS via CDMI, in this case

/cdmi_capabilities/dataobject/profile1

Managing QoS via CDMI

To manage the QoS of a CDMI data object or container and its equivalent representation with the specific storage back-end, you have to change the capabilitiesURI of an object.

This can be achieved with a PUT call and the capabilitiesURI in a JSON formatted payload.

Be aware that the transition needs to be supported at the storage back-end. Therefore please explorer the available CDMI capabilities first (as explained in the previous section) and keep in mind the capabilities URI e.g. /cdmi_capabilities/dataobject/profile1 and the cdmi_capabilities_allowed field.

In the previous example you can see, that for CDMI data objects two sets of capabilities are supported "cdmi_capabilities_allowed": "/cdmi_capabilities/dataobject/profile1 /cdmi_capabilities/dataobject/profile2".

This means that any data object referenced with either one of the capabilities URI can be transitioned to another set of capabilities as indicated.

PUT /myData

An example call to manage the QoS of a CDMI data object or container might look like the following, assuming there exists a /myData data object on the storage back-end.

curl -u restadmin:restadmin -H "X-CDMI-Specification-Version: 1.1" -H "Content-Type: application/cdmi-object" -X PUT http://localhost/myData -d@capabilities.json

with a capabilities.json file like the following.

{ "capabilitiesURI": "/cdmi_capabilities/dataobject/profile2" } If you query the object again during transition, it will have a cdmi_capabilities_target field indicating the target capabilities URI which references the desired QoS set of attributes.

If you query the object again after the transition, it will have the capabilitiesURI field updated to the desired QoS set of attributes.

Going on ...

You should now be able to do basic querying and QoS management via CDMI. To learn more about CDMI please have a look at the SNIA CDMI specification.

PreviousUser guide

Last updated