12    Capability Object Resource Operations

12.1   Overview

Capability objects allow a CDMI™ client to discover what subset of this international standard is implemented by a CDMI provider.

For each URI in a cloud storage system, the set of interactions that the system is capable of performing for that URI are described by the presence of named "capabilities". Each capability present for a given URI indicates what functionality the cloud storage system will allow against that URI. Capabilities are always static.

Capabilities may differ from the operations permitted by an Access Control List (ACL) (see 16.1) associated with a given URI‚ e.g., a read-only cloud may not permit write access to a container or object, despite the presence of an ACL allowing write access.

Cloud clients may use capabilities to discover what operations are supported. If an operation is attempted on a CDMI object that does not have a corresponding capability, an HTTP 400 status code shall be returned to the client. All CDMI-compliant cloud storage systems shall implement the ability to read capabilities, but support for the functionality indicated by each capability is optional.

Every CDMI data object, container object, domain object, and queue object shall have a capabilitiesURI field that contains a valid URI of a capabilities object. Within the capabilities object, the name of each capability confers a specific meaning that has been agreed to between the cloud storage provider and the cloud storage consumer.

The capabilities defined as part of this international standard are described starting in 12.1.1 "Cloud Storage System-Wide Capabilities". Vendor-defined capabilities not specified in this international standard shall not start with "cdmi_".

Figure 7 shows the hierarchy of capabilities in an offering and how the capabilitiesURI links data objects and container objects into the capabilities tree.

HierarchyofCapabilities.jpg

 

Figure 7 - Hierarchy of Capabilities

 

The capabilities container within the capabilities tree to which an object is linked is based on the type of the object and the data system metadata fields present in the object.

EXAMPLE   A container with no data system metadata fields specified may map to the "container" capabilities entry.

As an option, a CDMI implementation may map a container to a "gold_container" capabilities entry, if a data system metadata field is present and set to a given value, such as if the cdmi_data_redundancy field was set to the value of "4". This permits a cloud provider to create profiles of data system metadata fields and values.

Capabilities do not have a CDMI metadata field.

12.1.1   Cloud Storage System-Wide Capabilities

Table 101 defines the system-wide capabilities in a cloud storage system. These capabilities, which are found in the capabilities object, are referred to by the root URI (root capabilities).

Table 101 - System-Wide Capabilities

Capability Name

Type

Definition

cdmi_domains

JSON String

If present and "true", indicates that the cloud storage system supports domains. If not present, the domainURI field shall not be present in response message bodies and the cdmi_domains URI shall not be present.

cdmi_export_cifs

JSON String

If present and "true", this capability indicates that the cloud storage system supports CIFS exports.

cdmi_dataobjects

JSON String

If present and "true", this capability indicates that the cloud storage system supports data objects.

cdmi_export_iscsi

JSON String

If present and "true", this capability indicates that the cloud storage system supports iSCSI exports.

cdmi_export_nfs

JSON String

If present and "true", this capability indicates that the cloud storage system supports NFS protocol exports.

cdmi_export_occi_iscsi

JSON String

If present and "true", this capability indicates that the cloud storage system supports OCCI/iSCSI exports.

cdmi_export_webdav

JSON String

If present and "true", this capability indicates that the cloud storage system supports WebDAV exports.

cdmi_metadata_maxitems

JSON String

If present, this capability indicates the maximum number of user-defined metadata items supported per object. If absent, there is no limit placed on the number of user-defined metadata items.

cdmi_metadata_maxsize

JSON String

If present, this capability indicates the maximum size, in bytes, of each user-defined metadata item supported per object. If absent, there is no limit placed on the size of user-defined metadata items.

cdmi_metadata_maxtotalsize

JSON String

If present, this capability indicates the maximum size, in bytes, of user-defined metadata supported by the cloud storage system. If absent, there is no limit placed on the size of user-defined metadata.

cdmi_notification

JSON String

If present and "true", this capability indicates that the cloud storage system supports notification queues.

cdmi_logging

JSON String

If present and "true", this capability indicates that the cloud storage system supports logging queues.

cdmi_query

JSON String

If present and "true", this capability indicates that the cloud storage system supports query queues.

cdmi_query_regex

JSON String

If present and "true", this capability indicates that the cloud storage system supports query with regular expressions.

cdmi_query_contains

JSON String

If present and "true", this capability indicates that the cloud storage system supports query with "contains" expressions.

cdmi_query_tags

JSON String

If present and "true", this capability indicates that the cloud storage system supports query with tag-matching expressions.

cdmi_query_value

JSON String

If present and "true", this capability indicates that the cloud storage system supports query of value fields.

cdmi_queues

JSON String

If present and "true", this capability indicates that the cloud storage system supports queue objects.

cdmi_security_access_control

JSON String

If present and "true", this capability indicates that the cloud storage system supports ACLs. See 12.1.3 for additional information.

cdmi_security_audit

JSON String

If present and "true", this capability indicates that the cloud storage system supports audit logging. See 20.3 for additional information.

cdmi_security_data_integrity

JSON String

If present and "true", this capability indicates that the cloud storage system supports data integrity/authenticity. See 12.1.3 for additional information.

cdmi_security_encryption

JSON String

If present and "true", this capability indicates that the cloud storage system supports data at-rest encryption. See 12.1.3 for additional information.

cdmi_security_immutability

JSON String

If present and "true", this capability indicates that the cloud storage system supports data immutability/retentions. See 12.1.3 for additional information.

cdmi_security_sanitization

JSON String

If present and "true", this capability indicates that the cloud storage system supports data/media sanitization. See 12.1.3 for additional information.

cdmi_serialization_json

JSON String

If present and "true", this capability indicates that the cloud storage system supports JSON as a serialization format.

cdmi_snapshots

JSON String

If present and "true", this capability indicates that the cloud storage system supports snapshots.

cdmi_references

JSON String

If present and "true", this capability indicates that the cloud storage system supports references.

cdmi_object_move_from_local

JSON String

If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects from URIs within the same storage system.

cdmi_object_move_from_remote

JSON String

If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects from URIs within other CDMI storage systems.

cdmi_object_move_from_ID

JSON String

If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects without a path from a /cdmi_objectid/ URI within the same storage system. This effectively adds a path, allowing the object to be accessed by ID and by path.

cdmi_object_move_to_ID

JSON String

If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects with a path to a
/cdmi_objectid/ URI within the same storage system. This effectively removes the path, leaving the object only accessible by ID.

cdmi_object_copy_from_local

JSON String

If present and "true", this capability indicates that the cloud storage system supports copying CDMI objects from URIs within the same storage system.

cdmi_object_copy_from_remote

JSON String

If present and "true", this capability indicates that the cloud storage system supports copying CDMI objects from URIs within other CDMI storage systems.

cdmi_object_access_by_ID

JSON String

If present and "true", this capability indicates that objects can be accessed, updated, and deleted through "/cdmi_objectid/".

cdmi_post_dataobject_by_ID

JSON String

If present and "true", this capability indicates that the system allows a new data object by ID to be added via POST to
"/cdmi_objectid/".

cdmi_post_queue_by_ID

JSON String

If present and "true", this capability indicates that the system allows a new queue object by ID to be added via POST to
"/cdmi_objectid/".

cdmi_deserialize_dataobject_by_ID

JSON String

If present and "true", this capability indicates that the system allows the deserialization of serialized data objects when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_deserialize_queue_by_ID

JSON String

If present and "true", this capability indicates that the system allows the deserialization of serialized queue objects when creating a new queue object by ID via POST to "/cdmi_objectid/".

cdmi_serialize_dataobject_to_ID

JSON String

If present and "true", this capability indicates that the system allows the serialization of data objects when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_serialize_domain_to_ID

JSON String

If present and "true", this capability indicates that the system allows the serialization of domain objects when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_serialize_container_to_ID

JSON String

If present and "true", this capability indicates that the system allows the serialization of container objects when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_serialize_queue_to_ID

JSON String

If present and "true", this capability indicates that the system allows the serialization of queue objects when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_copy_dataobject_by_ID

JSON String

If present and "true", this capability indicates that the system allows the copying of an existing data object when creating a new data object by ID via POST to "/cdmi_objectid/".

cdmi_copy_queue_by_ID

JSON String

If present and "true", this capability indicates that the system allows the copying of an existing queue object when creating a new queue object by ID via POST to "/cdmi_objectid/".

cdmi_create_reference_by_ID

JSON String

If present and "true", this capability indicates that the system allows the creation of a new reference by IDa new child reference to be created via POST to "/cdmi_objectid/".

12.1.2   Storage System Metadata Capabilities

Table 102 defines the capabilities for storage system metadata in a cloud storage system. These capabilities are found in the capabilities objects for domains, data objects, containers, and queues. See 16.3 for a description of these storage system metadata items.

Table 102 - Capabilities for Storage System Metadata

Capability Name

Type

Definition

cdmi_acl

JSON String

If present and "true", this capability indicates that the cloud storage system supports ACLs. When a CDMI implementation supports ACLs for the purpose of access control, the system-wide capability of cdmi_security_access_control specified in Table 102 of 12.1.1 shall be set to "true". Otherwise, it shall not be present, indicating that there is no support for access control.

cdmi_size

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_size storage system metadata for each stored object.

cdmi_ctime

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_ctime storage system metadata for each stored object.

cdmi_atime

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_atime storage system metadata for each stored object.

cdmi_mtime

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_mtime storage system metadata for each stored object.

cdmi_acount

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_acount storage system metadata for each stored object.

cdmi_mcount

JSON String

If present and "true", this capability indicates that the cloud storage system shall generate a cdmi_mcount storage system metadata for each stored object.

12.1.3   Data System Metadata Capabilities

Table 103 defines the capabilities that indicate which data system metadata items are supported for objects stored in a cloud storage system. These capabilities are found in the capabilities objects for domains, data objects, containers, and queues. See 16.4 (Table 117) for a description of the meaning of the corresponding data system metadata items.

Table 103 - Capabilities for Data System Metadata

Capability Name

Type

Definition

cdmi_assignedsize

JSON String

When the cloud storage system supports the cdmi_assignedsize data system metadata as defined in 16.4, the cdmi_assignedsize capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_assignedsize data system metadata shall not be used.

cdmi_data_redundancy

JSON String

When the cloud storage system supports the cdmi_data_redundancy data system metadata as defined in 16.4, the cdmi_data_redundancy capability shall be present and set to a positive numeric string representing the maximum value that the server supports. When this capability is absent, or present and set to an empty string value "", cdmi_data_redundancy data system metadata shall not be used.

cdmi_data_dispersion

JSON String

When the cloud storage system supports the cdmi_data_dispersion data system metadata as defined in 16.4, the cdmi_data_dispersion capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_data_dispersion data system metadata shall not be used.

cdmi_data_retention

JSON String

When the cloud storage system supports both the cdmi_retention_id and cdmi_retention_period data system metadata as defined in 16.4, the cdmi_data_retention capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_retention_id and cdmi_retention_period data system metadata shall not be used.

cdmi_data_autodelete

JSON String

When the cloud storage system supports the cdmi_data_autodelete data system metadata as defined in 16.4, the cdmi_data_autodelete capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_data_autodelete data system metadata shall not be used.

cdmi_data_holds

JSON String

When the cloud storage system supports the cdmi_hold_id data system metadata as defined in 16.4, the cdmi_data_holds capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_data_holds data system metadata shall not be used.

When a cloud storage system supports holds for the purpose of making data immutable, the system-wide capability of cdmi_security_immutability specified in Table 101 of 12.1.1 shall be present and set to "true".

cdmi_encryption

JSON Array

When the cloud storage system supports the cdmi_encryption data system metadata as defined in 16.4, the cdmi_encryption capability shall be present and set to one or more values described in the cdmi_encryption data system metadata section in 16.4. When this capability is absent, or present and is an empty JSON array, cdmi_encryption data system metadata shall not be used.

When a cloud storage system supports at-rest encryption, the system-wide capability of cdmi_security_encryption specified in Table 101 of 12.1.1 shall be present and set to "true".

cdmi_geographic_placement

JSON String

When the cloud storage system supports the cdmi_geographic_placement data system metadata as defined in 16.4, the cdmi_geographic_placement capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_geographic_placement data system metadata shall not be used.

cdmi_immediate_redundancy

JSON String

When the cloud storage system supports the cdmi_immediate_redundancy data system metadata as defined in 16.4, the cdmi_immediate_redundancy capability shall be present and set to a positive numeric string representing the maximum value that the server supports. When this capability is absent, or present and set to an empty string value "", cdmi_immediate_redundancy data system metadata shall not be used.

cdmi_infrastructure_redundancy

JSON String

When the cloud storage system supports the cdmi_infrastructure_redundancy data system metadata as defined in 16.4, the cdmi_infrastructure_redundancy capability shall be present and set to a positive numeric string representing the maximum value that the server supports. When this capability is absent, or present and set to an empty string value "", cdmi_infrastructure_redundancy data system metadata shall not be used.

cdmi_latency

JSON String

When the cloud storage system supports the cdmi_latency data system metadata as defined in 16.4, the cdmi_latency capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_latency data system metadata shall not be used..

cdmi_RPO

JSON String

When the cloud storage system supports the cdmi_RPO data system metadata as defined in 16.4, the cdmi_RPO capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_RPO data system metadata shall not be used.

cdmi_RTO

JSON String

When the cloud storage system supports the cdmi_RTO data system metadata as defined in 16.4, the cdmi_RTO capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_RTO data system metadata shall not be used.

cdmi_sanitization_method

JSON Array

When the cloud storage system supports the cdmi_sanitization_method data system metadata as defined in 16.4, the cdmi_sanitization_method capability shall be present and set to one or more values described in the cdmi_sanitization_method data system metadata section in 16.4. When this capability is absent, or present and is an empty JSON array, cdmi_sanitization_method data system metadata shall not be used.

When a cloud storage system supports sanitization, the system-wide capability of cdmi_security_sanitization specified in Table 101 of 12.1.1 shall be present and set to "true".

cdmi_throughput

JSON String

When the cloud storage system supports the cdmi_throughput data system metadata as defined in 16.4, the cdmi_throughput capability shall be present and set to the string value "true". When this capability is absent, or present and set to the string value "false", cdmi_throughput data system metadata shall not be used.

cdmi_value_hash

JSON Array

When the cloud storage system supports the cdmi_value_hash data system metadata as defined in 16.4, the cdmi_value_hash capability shall be present and set to one or more values described in the cdmi_value_hash data system metadata section in 16.4. When this capability is absent, or present and is an empty JSON array, cdmi_value_hash data system metadata shall not be used.

When a cloud storage system supports value hashing, the system-wide capability of cdmi_security_data_integrity specified in Table 101 of 12.1.1 shall be present and set to "true".

12.1.4   Data Object Capabilities

Table 104 defines the capabilities for data objects in a cloud storage system.

Table 104 - Capabilities for Data Objects

Capability Name

Type

Definition

cdmi_read_value

JSON String

If present and "true", this capability indicates that the object’s value may be read.

cdmi_read_value_range

JSON String

If present and "true", this capability indicates that the object’s value may be read with byte ranges.

cdmi_read_metadata

JSON String

If present and "true", this capability indicates that the object’s metadata may be read.

cdmi_modify_value

JSON String

If present and "true", this capability indicates that the object’s value may be modified.

cdmi_modify_value_range

JSON String

If present and "true", this capability indicates that the object’s value may be modified with byte ranges.

cdmi_modify_metadata

JSON String

If present and "true", this capability indicates that the object’s metadata may be modified.

cdmi_modify_deserialize_dataobject

JSON String

If present and "true", this capability indicates that the data object permits the deserialization of a serialized data object into the data object as an update.

cdmi_delete_dataobject

JSON String

If present and "true", this capability indicates that the object may be deleted.

12.1.5   Container Capabilities

Table 105 defines the capabilities for containers in a cloud storage system.

Table 105 - Capabilities for Containers

Capability Name

Type

Definition

cdmi_list_children

JSON String

If present and "true", this capability indicates that the container’s children may be listed.

cdmi_list_children_range

JSON String

If present and "true", this capability indicates that the container’s children may be listed with ranges.

cdmi_read_metadata

JSON String

If present and "true", this capability indicates that the container’s metadata may be read.

cdmi_modify_metadata

JSON String

If present and "true", this capability indicates that the container’s metadata may be modified.

cdmi_modify_deserialize_container

JSON String

If present and "true", this capability indicates that the container object permits the deserialization of a serialized container object into the container object as an update.

cdmi_snapshot

JSON String

If present and "true", this capability indicates that the container allows a new snapshot to be created.

cdmi_serialize_dataobject

JSON String

If present and "true", this capability indicates that the object may be serialized.

cdmi_serialize_container

JSON String

If present and "true", this capability indicates that the container and all children’s contents may be serialized.

cdmi_serialize_queue

JSON String

If present and "true", this capability indicates that the queue may be serialized.

cdmi_serialize_domain

JSON String

If present and "true", this capability indicates that the domain and all child domains may be serialized.

cdmi_deserialize_container

JSON String

If present and "true", this capability indicates that the container permits the deserialization of serialized containers and associated serialized children into the container

cdmi_deserialize_queue

JSON String

If present and "true", this capability indicates that the container permits the deserialization of serialized queues into the container.

cdmi_deserialize_dataobject

JSON String

If present and "true", this capability indicates that the container permits the deserialization of serialized data objects into the container.

cdmi_create_dataobject

JSON String

If present and "true", this capability indicates that the container allows a new object to be added.

cdmi_post_dataobject

JSON String

If present and "true", this capability indicates that the container allows a new object to be added via POST.

cdmi_post_queue

JSON String

If present and "true", this capability indicates that the container allows a new queue to be added via POST.

cdmi_create_container

JSON String

If present and "true", this capability indicates that the container allows a new container to be created via PUT.

cdmi_create_queue

JSON String

If present and "true", this capability indicates that the container allows queues to be created.

cdmi_create_reference

JSON String

If present and "true", this capability indicates that the container allows a new child reference to be created via PUT.

cdmi_export_container_cifs

JSON String

If present and "true", the container can be exported as a file system via CIFS.

cdmi_export_container_nfs

JSON String

If present and "true", the container can be exported as a file system via NFS.

cdmi_export_container_iscsi

JSON String

If present and "true", the container can be exported as a file system via iSCSI.

cdmi_export_container_occi

JSON String

If present and "true", the container can be exported as a file system via OCCI.

cdmi_export_container_webdav

JSON String

If present and "true", the container can be exported as a file system via WebDAV.

cdmi_delete_container

JSON String

If present and "true", this capability indicates that the container may be deleted.

cdmi_move_container

JSON String

If present and "true", this capability indicates that a container object may be moved into the container.

cdmi_copy_container

JSON String

If present and "true", this capability indicates that a container object may be copied into the container.

cdmi_move_dataobject

JSON String

If present and "true", this capability indicates that a data object may be moved into the container.

cdmi_copy_dataobject

JSON String

If present and "true", this capability indicates that a data object may be copied into the container.

12.1.6   Domain Object Capabilities

Table 106 defines the capabilities for domains in a cloud storage system. (All capabilities refer to what may be done via CDMI content-type operations.)

Table 106 - Capabilities for Domain Objects

Capability Name

Type

Definition

cdmi_create_domain

JSON String

If present and "true", this capability indicates that the domain allows a new subdomain to be added.

cdmi_delete_domain

JSON String

If present and "true", this capability indicates that the domain may be deleted.

cdmi_domain_summary

JSON String

If present and "true", this capability indicates that the domain supports domain summaries.

cdmi_domain_members

JSON String

If present and "true", this capability indicates that the domain supports domain user management.

cdmi_list_children

JSON String

If present and "true", this capability indicates that the domain's children may be listed.

cdmi_read_metadata

JSON String

If present and "true", this capability indicates that the domain's metadata may be read.

cdmi_modify_metadata

JSON String

If present and "true", this capability indicates that the domain's metadata may be modified.

cdmi_modify_deserialize_domain

JSON String

If present and "true", this capability indicates that the domain object permits the deserialization of a serialized domain object into the domain object as an update.

cdmi_copy_domain

JSON String

If present and "true", this capability indicates that the domain may be copied (via PUT) to another URI.

cdmi_deserialize_domain

JSON String

If present and "true", this capability indicates that the domain permits the deserialization of serialized domains and associated serialized children into the domain.

12.1.7   Queue Object Capabilities

Table 107 defines the capabilities for queue objects in a cloud storage system.

Table 107 - Capabilities for Queue Objects

Capability Name

Type

Definition

cdmi_read_value

JSON String

If present and "true", this capability indicates that the queue's value may be read.

cdmi_read_metadata

JSON String

If present and "true", this capability indicates that the queue's metadata may be read.

cdmi_modify_value

JSON String

If present and "true", this capability indicates that the queue's value may be modified.

cdmi_modify_metadata

JSON String

If present and "true", this capability indicates that the queue's metadata may be modified.

cdmi_modify_deserialize_queue

JSON String

If present and "true", this capability indicates that the queue permits the deserialization of a serialized queue into the queue as an update.

cdmi_delete_queue

JSON String

If present and "true", this capability indicates that the queue may be deleted.

cdmi_move_queue

JSON String

If present and "true", this capability indicates that the queue may be moved to another URI.

cdmi_copy_queue

JSON String

If present and "true", this capability indicates that the queue may be copied to another URI.

cdmi_reference_queue

JSON String

If present and "true", this capability indicates that the queue may be referenced from another queue.

12.1.8   Capability Object Representations

The representations in this clause are shown using JSON notation. Both clients and servers shall support UTF-8 JSON representation. The request and response message body JSON fields may be specified or returned in any order, with the exception that, if present, for capability objects, the childrenrange and children fields shall appear last and in that order.

12.2   Read a Capabilities Object using CDMI Content Type

12.2.1   Synopsis

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

GET <root URI>/cdmi_capabilities/<Capability>/<TheCapability>/

To read one or more requested fields from an existing capability object, one of the following requests shall be performed:

GET <root URI>/cdmi_capabilities/<Capability>/<TheCapability>/?<fieldname>;<fieldname>

GET <root URI>/cdmi_capabilities/<Capability>/<TheCapability>/?children:<range>

Where:

   <root URI> is the path to the CDMI cloud.

   <Capability> is zero or more intermediate capabilities containers.

   <TheCapability> is the name specified for the capabilities to be read from.

   <fieldname> is the name of a field.

   <range> is a numeric range within the list of children.

The object shall also be accessible at <root URI>/cdmi_objectid/<objectID>/.

12.2.2   Capability

The following capability describes the supported operations that may be performed when reading an existing capabilities object:

   All CDMI implementations shall permit clients to read all fields of all capabilities objects.

12.2.3   Request Headers

The HTTP request headers for reading a CDMI capabilities object using CDMI content type are shown in Table 108.

Table 108 - Request Headers - Read a Capabilities Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

"application/cdmi-capability" or a consistent value as per clause 5.13.2

Optional

X-CDMI-Specification-Version

String Array

A comma-separated list of versions supported by the client, e.g., "1.0.2, 1.5, 2.0"

Mandatory

12.2.4   Request Message Body

A request message body shall not be provided.

12.2.5   Response Headers

 The HTTP response headers for reading a CDMI capabilities object using CDMI content type are shown in Table 109.

Table 109 - Response Headers - Read a Capabilities Object using CDMI Content Type

Header

Type

Description

Requirement

X-CDMI-Specification-Version

Header String

The server shall respond with the highest version supported by both the client and the server, e.g., "1.0.2".

If the server does not support any of the versions supported by the client, the server shall return a 400 Bad Request status code.

Mandatory

Content-Type

Header String

"application/cdmi-capability"

Mandatory

12.2.6   Response Message Body

The response message body fields for reading a CDMI capabilities object using CDMI content type are shown in Table 110.

Table 110 - Response Message Body - Read a Capabilities Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-capability"

Mandatory

objectID

JSON String

Object ID 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 container object

Mandatory

capabilities

JSON Object

The capabilities supported by the corresponding object. Capabilities in the "/cdmi_capabilities/" object are system-wide capabilities. Capabilities found in children objects under "/cdmi_capabilities/" correspond to the capabilities of a specific subset of objects. Each capability is expressed as a JSON string.

Mandatory

childrenrange

JSON String

The child capabilities of the capability expressed as a range. If a range of child capabilities is requested, this field indicates the children returned as a range.

Mandatory

children

JSON Array

Names of the children capabilities objects. For the root container capabilities, this includes "domain/", "container/", "dataobject/", and "queue/". Within each of these capabilities objects, further more specialized capabilities profiles may be specified by the cloud storage system.

Mandatory

If individual fields are specified in the GET request, only these fields are returned in the result body. Optional fields that are requested but do not exist are omitted from the result body.

12.2.7   Response Status

Table 111 describes the HTTP status codes that occur when reading a capabilities object using CDMI content type.

Table 111 - HTTP Status Codes - Read a Capabilities Object using CDMI Content Type

HTTP Status

Description

200 OK

The capabilities object content was returned in the reponse.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The resource was not found at the specified URI.

406 Not Acceptable

The server is unable to provide the object in the content type specified in the Accept header.

12.2.8   Examples

EXAMPLE 1   GET to the root container capabilities URI to read all fields of the container:

GET /cdmi_capabilities/ HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

 

{

   "objectType" : "application/cdmi-capability",

   "objectID" : "00007E7F00104BE66AB53A9572F9F51E",

   "objectName" : "cdmi_capabilities/",

   "parentURI" : "/",

    "parentID" : "00007E7F0010128E42D87EE34F5A6560",

   "capabilities" : {

       "cdmi_domains" : "true",

       "cdmi_export_nfs" : "true",

       "cdmi_export_iscsi" : "true",

       "cdmi_queues" : "true",

       "cdmi_notification" : "true",

       "cdmi_query" : "true",

       "cdmi_metadata_maxsize" : "4096",

        "cdmi_metadata_maxitems" : "1024"

   },

   "childrenrange" : "0-3",

   "children" : [

       "domain/",

       "container/",

       "dataobject/",

        "queue/"

   ]

}

EXAMPLE 2   GET to the root container capabilities URI to read the capabilities and children of the container:

GET /cdmi_capabilities/?capabilities;children HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

 

{

   "capabilities" : {

       "cdmi_domains" : "true",

       "cdmi_export_nfs" : "true",

       "cdmi_export_iscsi" : "true",

       "cdmi_queues" : "true",

       "cdmi_notification" : "true",

       "cdmi_query" : "true",

       "cdmi_metadata_maxsize" : "4096",

        "cdmi_metadata_maxitems" : "1024"

   },

   "children" : [

       "domain/",

       "container/",

       "dataobject/",

        "queue/"

   ]

}

EXAMPLE 3   GET to the root container capabilities URI to read the first two children of the container:

GET /cdmi_capabilities/?childrenrange;children:0-1 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-capability

X-CDMI-Specification-Version: 1.0.2

 

{

   "childrenrange" : "0-1",

   "children" : [

       "domain/",

        "container/"

   ]

}