9    Container Object Resource Operations

9.1   Overview

Container objects are the fundamental grouping of stored data within CDMI™ and are analogous to directories within a file system. Each container object has zero or more child objects and a set of well-defined fields that include standardized and optional metadata. The metadata is generated by the cloud storage system and specified by the cloud user.

Containers are addressed in CDMI in two ways:

   by name (e.g., http://cloud.example.com/container/); and

   by object ID (e.g., http://cloud.example.com/cdmi_objectid/0000706D0010B84FAD185C425D8B537E.

Every container object has a single, globally-unique object ID that remains constant for the life of the object. Each container object may also have one or more URI addresses that allow the container object to be accessed. Following the URI conventions for hierarchical paths, container URIs shall consist of one or more container names that are separated by forward slashes ("/") and that end with a forward slash ("/").

If a request is performed against an existing container resource and the trailing slash at the end of the URI is omitted, the server shall respond with an HTTP status code of 301 Moved Permanently, and a Location header containing the URI with the trailing slash will be added.

If a CDMI request is performed to create a new container resource and the trailing slash at the end of the URI is omitted, the server shall respond with an HTTP status code of 400 Bad Request.

Non-CDMI requests to create a container resource shall include the trailing slash at the end of the URI; otherwise, the request shall be considered a request to create a data object.

Containers may also be nested.

EXAMPLE 1   The following URI represents a nested container:

http://cloud.example.com/container/subcontainer/

A nested container has a parent container object, shall be included in the children field of the parent container object, and shall inherit data system metadata and ACLs from its parent container.

This model allows direct mapping between CDMI-managed cloud storage and file systems (e.g., NFSv4 or WebDAV). If a CDMI container object is exported as a file system, then the file system may make the CDMI metadata accessible via file system-specific mechanisms. As files and directories are created by the file system, they become visible through the CDMI interface acting as a data path. The mapping between file system constructs and CDMI data objects, container objects, and metadata is outside the scope of this international standard.

Individual fields within a container object may be accessed by specifying the field name after a question mark "?" appended to the end of the container object URI.

EXAMPLE 2   The following URI returns just the children field in the response message body:

http://cloud.example.com/container/?children

By specifying a range after the children field name, specific ranges of the children field may be accessed.

EXAMPLE 3   The following URI returns the first three children from the children field:

http://cloud.example.com/container/?children:0-2

Children ranges are specified in a way that is similar to byte ranges as per Section 14.35.1 of RFC 2616. A client can determine the number of children present by requesting the childrenrange field without requesting a range of children.

A list of fields, separated by a semicolon ";" may be specified, allowing multiple fields to be accessed in a single request.

EXAMPLE 4   The following URI would return the children and metadata fields in the response message body:

http://cloud.example.com/container/?children;metadata

When a client provides or includes deserialization fields that are not defined in this international standard, these fields shall be stored as part of the object.

9.1.1   Container Metadata

The following optional data system metadata may be provided (see Table 31).

Table 31 - Container Metadata

Metadata Name

Type

Description

Requirement

cdmi_assignedsize

JSON String

The number of bytes that is reported via exported protocols (e.g., the device may be thin provisioned). This number may limit cdmi_size.

Optional

Container metadata may also include arbitrary user-supplied metadata and data system metadata as described in Clause 16.

9.1.2   Reserved Container Names

This international standard defines reserved container names that shall not be used when creating new containers. These container names are reserved for use by this international standard, and if an attempt is made to create or delete them, an HTTP 400 Bad Request result code shall be returned to the client.

The reserved container names include:

   cdmi_objectid,

   cdmi_domains,

   cdmi_capabilities,

   cdmi_snapshots, and

   cdmi_versions.

As additional names may be added in future versions of this international standard, server implementations shall prevent the creation of user-defined containers if the container name starts with "cdmi_".

9.1.3   Container Object Addressing

Each container object is addressed via one or more unique URIs, and all operations may be performed through any of these URIs. For example, a container object may be accessible via multiple virtual hosting paths, where http://cloud.example.com/users/snia/cdmi/ is also accessible through http://snia.example.com/cdmi/. Conflicting writes via different paths shall be managed the same way that conflicting writes via one path are managed, via the principle of eventual consistency (see 9.2).

9.1.4   Container 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 container objects, the childrenrange and children fields shall appear last and in that order. 

9.2   Create a Container Object using CDMI Content Type

9.2.1   Synopsis

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

PUT <root URI>/<ContainerName>/<NewContainerName>/

Where:

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

   <ContainerName> is zero or more intermediate container objects that already exist, with one slash (i.e., "/") between each pair of container object names.

   <NewContainerName> is the name specified for the container object to be created.

After it is created, the container object shall also be accessible at <root URI>/cdmi_objectid/<objectID>/.

9.2.2   Delayed Completion of Create

In response to a create operation for a container object, the server may return 202 Accepted to indicate that the object is in the process of being created. This response is useful for long-running operations (e.g., deserializing a source data object to create a large container object hierarchy). Such a response has the following implications.

   The server shall return a Location header with a URI to the object to be created along with an HTTP status code of 202 Accepted.

   With 202 Accepted, the server implies that the following checks have passed:

   user authorization for creating the container object;

   user authorization for read access to any source object for move, copy, serialize, or deserialize; and

   availability of space to create the container object or at least enough space to create a URI to report an error.

   A client might not be able to immediately access the created object, e.g., due to delays resulting from the implementation’s use of eventual consistency.

The client performs GET operations to the URI to track the progress of the operation. In response, the server returns two fields in its response message body to indicate progress.

   A mandatory completionStatus text field contains either "Processing", "Complete", or an error string starting with the value "Error".

   An optional percentComplete field contains the percentage that the accepted PUT has completed (0 to 100). GET does not return any children for the container object when completionStatus is not "Complete".

When the final result of the create operation is an error, the URI is created with the completionStatus field set to the error message. It is the client's responsibility to delete the URI after the error has been noted.

9.2.3   Capabilities

The following capabilities describe the supported operations that may be performed when creating a new container object:

   Support for the ability to create a new container object is indicated by the presence of the cdmi_create_container capability in the parent container object.

   If the object being created in the parent container object is a reference, support for that ability is indicated by the presence of the cdmi_create_reference capability in the parent container object.

   If the new container object is a copy of an existing container object, support for the ability to copy is indicated by the presence of the cdmi_copy_container capability in the parent container object.

   If the new container object is the destination of a move, support for the ability to move the container object is indicated by the presence of the cdmi_move_container capability in the parent container object.

   If the new container object is the destination of a deserialize operation, support for the ability to deserialize the source data object serialization of a container object is indicated by the presence of the cdmi_deserialize_container capability in the parent container object.

9.2.4   Request Headers

The HTTP request headers for creating a CDMI container object using CDMI content type are shown in Table 32.

Table 32 - Request Headers - Create a Container Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

Content-Type

Header String

"application/cdmi-container"

Mandatory

X-CDMI-Specification-Version

Header String

A comma-separated list of versions supported by the client, for example, "1.0.2, 1.5, 2.0"

Mandatory

9.2.5   Request Message Body

The request message body fields for creating a container object using CDMI content type are shown in Table 33.

Table 33 - Request Message Body - Create a Container Object using CDMI Content Type

Field Name

Type

Description

Requirement

metadata

JSON Object

Metadata for the container object

   If this field is included when deserializing, serializing, copying, or moving a container object, the value provided in this field shall replace the metadata from the source URI.

   If this field is not included when deserializing, serializing, copying, or moving a container object, the metadata from the source URI shall be used.

   If this field is included when creating a new container object by specifying a value, the value provided in this field shall be used as the metadata.

   If this field is not included when creating a new container object by specifying a value, an empty JSON object (i.e., "{}") shall be assigned as the field value.

   This field shall not be included when referencing a container object.

Optional

domainURI

JSON String

URI of the owning domain

   If different from the parent domain, the user shall have the cross_domain privilege (see cdmi_member_privileges in Table 64).

   If not specified, the parent domain shall be used.

Optional

exports

JSON Object

A structure for each protocol enabled for this container object (see Clause 13). This field shall not be included when referencing a container object.

Optional

deserialize

JSON String

URI of a serialized CDMI data object that shall be deserialized to create the new container object, including all child objects inside the source serialized data object (see Clause 15).

When deserializing a container object, any exported protocols from the original serialized container object are not applied to the newly created container object(s).

Optionala

copy

JSON String

URI of a CDMI container object that shall be copied into the new container object, including all child objects under the source container object. When copying a container object, exported protocols are not preserved across the copy.

Optionala

move

JSON String

URI of an existing local or remote CDMI container object (source URI) that shall be relocated, along with all child objects, to the URI specified in the PUT. The contents of the container object and all children, including the object ID, shall be preserved by a move, and the container object and all children of the source URI shall be removed after the objects at the destination have been successfully created.

If there are insufficient permissions to read the objects at the source URI, write the objects at the destination URI, or delete the objects at the source URI, or if any of these operations fail, the move shall return a 400 Bad Request result code, and the source and destination are left unchanged.

Optionala

reference

JSON String

URI of a CDMI container object that shall be redirected to by a reference. If other fields are supplied when creating a reference, the server shall respond with an HTTP status code of 400 Bad Request.

Optionala

deserializevalue

JSON String

A container object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648. The object ID of the serialized container object shall match the object ID of the destination container object.

Optionala

aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored. If more than one of these fields is supplied, the server shall respond with a 400 Bad Request error response.

9.2.6   Response Headers

The HTTP response headers for creating a CDMI container object using CDMI content type are shown in Table 34.

Table 34 - Response Headers - Create a Container Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-container"

Mandatory

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

9.2.7   Response Message Body

The response message body fields for creating a CDMI container object using CDMI content type are shown in Table 35.

Table 35 - Response Message Body - Create a Container Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-container"

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

Appending the objectName to the parentURI shall always produce a valid URI for the object.

Mandatory

parentID

JSON String

Object ID of the parent container object

Mandatory

domainURI

JSON String

URI of the owning domain

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

completionStatus

JSON String

A string indicating if the object is still in the process of being created, and after the operation is complete, if it was created successfully or an error occurred. The value shall be the string "Processing", the string "Complete", or an error string starting with the value "Error".

Mandatory

percentComplete

JSON String

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer value from 0 through 100.

Optional

metadata

JSON Object

Metadata for the container object. This field includes any user and data system metadata specified in the request message body metadata field, along with storage system metadata generated by the cloud storage system. See Clause 16 for a further description of metadata.

Mandatory

exports

JSON Object

A structure for each protocol that is enabled for this container object. See Clause 13.

Optionala 

snapshots

JSON Array

URI(s) of the snapshot container objects. See Clause 14.

Optionala 

childrenrange

JSON String

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

Mandatory

children

JSON Array

Names of the children objects in the container object. Child container objects end with "/".

Mandatory

aReturned only if present.

9.2.8   Response Status

Table 36 describes the HTTP status codes that occur when creating a container object using CDMI content type.

Table 36 - HTTP Status Codes - Create a CDMI Container Object using CDMI Content Type

HTTP Status

Description

201 Created

The new container object was created.

202 Accepted

The container object is in the process of being created. The CDMI client should monitor the completionStatus and percentComplete fields to determine the current status of the operation.

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.

409 Conflict

The container object name already exists.

9.2.9   Example

EXAMPLE   PUT to the URI the container object name and metadata:

PUT /MyContainer/HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-container

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

        

   },

   "exports" : {

       "OCCI/iSCSI": {

       "identifier": "00007E7F00104BE66AB53A9572F9F51E",

       "permissions": [

           "http://example.com/compute/0/",

           "http://example.com/compute/1/"

       ]

   },

 

       "Network/NFSv4" : {

           "identifier" : "/users",

            "permissions" : "domain"

        }

   }

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "MyContainer/",

   "parentURI" : "/",

    "parentID" : "00007E7F0010128E42D87EE34F5A6560",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/container/",

   "completionStatus" : "Complete",

   "metadata" : {

        

   },

   "exports" : {

       "OCCI/iSCSI" : {

           "identifier" : "0000706D0010B84FAD185C425D8B537E",

            "permissions" : "00007E7F00104EB781F900791C70106C"

       },

       "Network/NFSv4" : {

           "identifier" : "/users",

            "permissions" : "domain"

        }

   },

   "childrenrange" : "",

   "children" : [

        

   ]

}

9.3   Create a Container Object using a Non-CDMI Content Type

9.3.1   Synopsis

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

PUT <root URI>/<ContainerName>/<NewContainerName>/

Where:

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

   <ContainerName> is zero or more intermediate container objects that already exist, with one slash (i.e., "/") between each pair of container object names.

   <NewContainerName> is the name specified for the container object to be created.

After it is created, the container object shall also be accessible at <root URI>/cdmi_objectid/<objectID>/.

The presence of a trailing slash at the end of the HTTP PUT URI indicates that a container object is being created and distinguishes it from a request to create a data object.

9.3.2   Capability

The following capability describes the supported operations that may be performed when creating a new container object:

   Support for the ability to create a new container object is indicated by the presence of the cdmi_create_container capability in the parent container object.

9.3.3   Request Headers

Request headers may be provided as per RFC 2616.

9.3.4   Request Message Body

A request message body shall not be provided.

9.3.5   Response Headers

Response headers may be provided as per RFC 2616.

9.3.6   Response Message Body

A response message body may be provided as per RFC 2616.

9.3.7   Response Status

Table 37 describes the HTTP status codes that occur when creating a container object using a non-CDMI content type.

Table 37 - HTTP Status Codes - Create a Container Object using a Non-CDMI Content Type

HTTP Status

Description

201 Created

The new container object was created.

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.

409 Conflict

The container object name already exists.

9.3.8   Example

EXAMPLE   PUT to the URI the container object name:

PUT /MyContainer/ HTTP/1.1

Host: cloud.example.com

The following shows the response.

HTTP/1.1 201 Created

9.4   Read a Container Object using CDMI Content Type

9.4.1   Synopsis

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

GET <root URI>/<ContainerName>/<TheContainerName>/

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

GET <root URI>/<ContainerName>/<TheContainerName>/?<fieldname>;<fieldname>;...

GET <root URI>/<ContainerName>/<TheContainerName>/?children:<range>;...

GET <root URI>/<ContainerName>/<TheContainerName>/?metadata:<prefix>;...

Where:

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

   <ContainerName> is zero or more intermediate container objects.

   <TheContainerName> is the name specified for the container object to be read from.

   <fieldname> is the name of a field.

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

   <prefix> is a matching prefix that returns all metadata items that start with the prefix value.

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

9.4.2   Capabilities

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

   Support for the ability to read the metadata of an existing container object is indicated by the presence of the cdmi_read_metadata capability in the specified container object.

   Support for the ability to list the children of an existing container object is indicated by the presence of the cdmi_list_children capability in the specified container object.

   Support for the ability to list ranges of the children of an existing container object is indicated by the presence of the cdmi_list_children_range capability in the specified container object.

9.4.3   Request Headers

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

Table 38 - Request Headers - Read a Container Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

X-CDMI-Specification-Version

Header String

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

Mandatory

9.4.4   Request Message Body

A request message body shall not be provided.

9.4.5   Response Headers

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

Table 39 - Response Headers - Read a Container 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-container"

Mandatory

Location

Header String

The server shall respond with the URI that the reference redirects to if the object is a reference.

Conditional

9.4.6   Response Message Body

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

Table 40 - Response Message Body - Read a Container Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-container"

Mandatory

objectID

JSON String

Object ID of the object

Mandatory

objectName

JSON String

Name of the object

   For objects in a container, the objectName field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the objectName field does not exist and shall not be returned.

Conditional

parentURI

JSON String

URI for the parent object

   For objects in a container, the parentURI field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentURI field does not exist and shall not be returned.

Appending the objectName to the parentURI shall always produce a valid URI for the object.

Conditional

parentID

JSON String

Object ID of the parent container object

   For objects in a container, the parentID field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentID field does not exist and shall not be returned.

Conditional

domainURI

JSON String

URI of the owning domain

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

completionStatus

JSON String

A string indicating if the object is still in the process of being created, and after the operation is complete, if it was created successfully or an error occurred. The value shall be the string "Processing", the string "Complete", or an error string starting with the value "Error".

Mandatory

percentComplete

JSON String

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer value from 0 through 100.

Optional

metadata

JSON Object

Metadata for the container object. This field includes any user and data system metadata specified in the request message body metadata field, along with storage system metadata generated by the cloud storage system. See Clause 16 for a further description of metadata.

Mandatory

exports

JSON Object

A structure for each protocol that is enabled for this container object (see Clause 13)

Optionala

snapshots

JSON Array

URIs of the snapshot container objects

Optionala

childrenrange

JSON String

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

Mandatory

children

JSON Array

Names of the children objects in the container object. All children names shall have reserved characters escaped according to RFC 3986, e.g., the "%" character in a name would be replaced with "%25".

   Children that are container objects shall have "/" appended to the child name.

   Children that are references shall have "?" appended to the child name.

Mandatory

aReturned only if present.

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.

9.4.7   Response Status

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

Table 41 - HTTP Status Codes - Read a Container Object using CDMI Content Type

HTTP Status

Description

200 OK

The metadata for the container object is provided in the message body.

302 Found

The URI is a reference to another URI.

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.

9.4.8   Examples

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

GET /MyContainer/HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "MyContainer/",

   "parentURI" : "/",

   "parentID" : "00007E7F0010128E42D87EE34F5A6560",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/container/",

   "completionStatus" : "Complete",

   "metadata" : {

        

   },

   "exports" : {

       "OCCI/iSCSI": {

       "identifier": "00007E7F00104BE66AB53A9572F9F51E",

       "permissions": [

           "http://example.com/compute/0/",

           "http://example.com/compute/1/"

       ]

   },

       "Network/NFSv4" : {

           "identifier" : "/users",

            "permissions" : "domain"

       },

       "childrenrange" : "0-4",

       "children" : [

           "red",

           "green",

           "yellow",

           "orange/",

            "purple/"

        ]

   }

}

EXAMPLE 2   GET to the container object URI to read parentURI and children of the container object:

GET /MyContainer/?parentURI;children HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

   "parentURI" : "/",

   "children" : [

       "red",

       "green",

       "yellow",

       "orange/",

        "purple/"

   ]

}

EXAMPLE 3   GET to the container object URI to read children 0..2 and childrenrange of the container object:

GET /MyContainer/?childrenrange;children:0-2 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

   "childrenrange" : "0-2",

   "children" : [

       "red",

       "green",

        "yellow"

   ]

}

9.5   Update a Container Object using CDMI Content Type

9.5.1   Synopsis

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

PUT <root URI>/<ContainerName>/<TheContainerName>/

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

PUT <root URI>/<ContainerName>/<TheContainerName>/?metadata:<metadataname>;...

Where:

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

   <ContainerName> is zero or more intermediate container objects.

   <TheContainerName> is the name of the container object to be updated.

The container object shall also be accessible at <root URI>/cdmi_objectid/<objectID>/. An update shall not result in a change to the object ID.

9.5.2   Delayed Completion of Snapshot

If the creation of a snapshot (see Clause 14) is requested by including a snapshot field in the request message body, the server may return an HTTP status code of 202 Accepted. Such a response has the following implications:

   With 202 Accepted, the server implies that the following checks have passed:

   user authorization for creating the snapshot,

   user authorization for read access to the container object, and

   availability of space to create the snapshot or at least enough space to create a URI to report an error.

   A client might not be able to immediately access the snapshot, e.g., due to delays resulting from the implementation’s use of eventual consistency.

The client performs GET operations to the snapshot URI to track the progress of the operation. In particular, the server returns two fields in its response message body to indicate progress:

   A completionStatus text field contains either "Processing", "Complete", or an error string starting with the value "Error".

   An optional percentComplete field contains the percentage that the accepted PUT has completed (0 to 100). GET does not return any value for the object when completionStatus is not "Complete".

When the final result of the snapshot operation is an error, the snapshot URI is created with the completionStatus field set to the error message. It is the client's responsibility to delete the URI after the error has been noted.

9.5.3   Capabilities

The following capabilities describe the supported operations that may be performed when updating an existing container object:

   Support for the ability to modify the metadata of an existing container object is indicated by the presence of the cdmi_modify_metadata capability in the specified container object.

   Support for the ability to snapshot the contents of an existing container object is indicated by the presence of the cdmi_snapshot capability in the specified container object.

   Support for the ability to add an exported protocol to an existing container object is indicated by the presence of the cdmi_export_<protocol> capabilities for the specified container object.

9.5.4   Request Headers

The HTTP request headers for updating a CDMI container object using CDMI content type are shown in Table 42.

Table 42 - Request Headers - Update a Container Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-container"

Mandatory

X-CDMI-Specification-Version

Header String

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

Mandatory

9.5.5   Request Message Body

The request message body fields for updating a container object using CDMI content type are shown in Table 43.

Table 43 - Request Message Body - Update a Container Object using CDMI Content Type

Field Name

Type

Description

Requirement

metadata

JSON Object

Metadata for the container object. If present, the new metadata specified replaces the existing object metadata. If individual metadata items are specified in the URI, only those items are replaced, with other items being preserved.

See Clause 16 for a further description of metadata.

Optional

domainURI

JSON String

URI of the owning domain

   If different from the parent domain, the user shall have the cross_domain privilege (see cdmi_member_privileges in Table 64).

   If not specified, the parent domain shall be used.

Optional

snapshot

JSON String

Name of the snapshot to be taken. This is not a URL, but rather the final component of the absolute URL where the snapshot will exist when the snapshot operation successfully completes. If a snapshot is added or changed, the PUT operation only returns after the snapshot is added to the snapshot list. After they are created, snapshots may be accessed as children container objects under the cdmi_snapshots child container object of the container object receiving a snapshot.

When creating a snapshot with the same name as an existing snapshot, the new snapshot will replace the existing snapshot.

Optional

deserialize

JSON String

URI of a serialized CDMI container object that shall be deserialized to update an existing container object. The object ID of the serialized container object shall match the object ID of the destination container object.

If the serialized container object does not contain children, the update is applied only to the container object, and any existing children are left as-is. If the serialized container object does contain children, then creates, updates, and deletes are recursively applied for each child, depending on the differences between the provided serialized state and the current state of the child.

Optionala

copy

JSON String

URI of a CDMI container object that shall be copied into the existing container object. Only the contents of the container object itself shall be copied, not any children of the container object.

Optionala

deserializevalue

JSON Sting

A container object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648.

The object ID of the serialized container object shall match the object ID of the destination container object. Otherwise, the server shall return an HTTP status code of 400 Bad Request.

   If the serialized container object does not contain children, the update is applied only to the container object, and any existing children are left as-is.

   If the serialized container object does contain children, then creates, updates, and deletes are recursively applied for each child, depending on the differences between the provided serialized state and the current state of the children.

Optionala

exports

JSON Object

A structure for each protocol that is enabled for this container object (see Clause 13). If an exported protocol is added or altered, the PUT operation only returns after the export operation has completed.

Optional

aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored.

9.5.6   Response Header

The HTTP response header for updating a CDMI container object using CDMI content type is shown in Table 44.

Table 44 - Response Header - Update a Container Object using CDMI Content Type

Header

Type

Description

Requirement

Location

Header String

The server shall respond with the URI that the reference redirects to if the object is a reference.

Conditional

9.5.7   Response Message Body

A response message body may be provided as per RFC 2616.

9.5.8   Response Status

Table 45 describes the HTTP status codes that occur when updating a container object using CDMI content type.

Table 45 - HTTP Status Codes - Update a Container Object using CDMI Content Type

HTTP Status

Description

204 No Content

The operation was successful; no data was returned.

202 Accepted

The container or snapshot (subcontainer object) is in the process of being created. The CDMI client should monitor the completionStatus and percentComplete fields to determine the current status of the operation.

302 Found

The URI is a reference to another URI.

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.

409 Conflict

The operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server.

9.5.9   Examples

EXAMPLE 1   PUT to the container object URI to set new field values:

PUT /MyContainer/ HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

        

   } ,

   "exports" : {

      "OCCI/iSCSI": {

       "identifier": "00007E7F00104BE66AB53A9572F9F51E",

       "permissions": [

           "http://example.com/compute/0/",

           "http://example.com/compute/1/"

       ]

   },

       "Network/NFSv4" : {

           "identifier" : "/users",

            "permissions" : "domain"

        }

   }

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 2   PUT to the container object URI to set a new exported protocol value:

PUT /MyContainer/?exports HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-container

X-CDMI-Specification-Version: 1.0.2

 

{

   "exports" : {

       "OCCI/iSCSI" : {

           "identifier" : "0000706D0010B84FAD185C425D8B537E",

            "permissions" : "00007E7F00104EB781F900791C70106C"

       } ,

       "Network/NFSv4" : {

           "identifier" : "/users",

            "permissions" : "domain"

        }

   }

}

The following shows the response.

HTTP/1.1 204 No Content

9.6   Delete a Container Object using CDMI Content Type

9.6.1   Synopsis

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

DELETE <root URI>/<ContainerName>/<TheContainerName>/

Where:

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

   <ContainerName> is zero or more intermediate container objects.

   <TheContainerName> is the name of the container object to be deleted.

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

9.6.2   Capability

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

   Support for the ability to delete an existing data object is indicated by the presence of the cdmi_delete_container capability in the specified container object.

9.6.3   Request Header

The HTTP request header for deleting a CDMI container object using CDMI content type is shown in Table 46.

Table 46 - Request Header - Delete a Container Object using CDMI Content Type

Header

Type

Description

Requirement

X-CDMI-Specification-Version

Header String

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

Mandatory

9.6.4   Request Message Body

A request message body may be provided as per RFC 2616.

9.6.5   Response Headers

Response headers may be provided as per RFC 2616.

9.6.6   Response Message Body

A response message body may be provided as per RFC 2616.

9.6.7   Response Status

Table 47 describes the HTTP status codes that occur when deleting a container object using CDMI content type.

Table 47 - HTTP Status Codes - Delete a Container Object using CDMI Content Type

HTTP Status

Description

204 No Content

The container object was successfully deleted.

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.

409 Conflict

The container object may not be deleted.

9.6.8   Example

EXAMPLE   DELETE to the container object URI:

DELETE /MyContainer/ HTTP/1.1

Host: cloud.example.com

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 204 No Content

9.7   Delete a Container Object using a Non-CDMI Content Type

9.7.1   Synopsis

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

DELETE <root URI>/<ContainerName>/<TheContainerName>/

Where:

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

   <ContainerName> is zero or more intermediate container objects.

   <TheContainerName> is the name of the container object to be deleted.

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

9.7.2   Capability

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

   Support for the ability to delete an existing data object is indicated by the presence of the cdmi_delete_container capability in the specified container object.

9.7.3   Request Headers

Request headers may be provided as per RFC 2616.

9.7.4   Request Message Body

A request message body may be provided as per RFC 2616.

9.7.5   Response Headers

Response headers may be provided as per RFC 2616.

9.7.6   Response Message Body

A response message body may be provided as per RFC 2616.

9.7.7   Response Status

Table 48 describes the HTTP status codes that occur when deleting a container object using a non-CDMI content type.

Table 48 - HTTP Status Codes - Delete a Container Object using a Non-CDMI Content Type

HTTP Status

Description

204 No Content

The container object was successfully deleted.

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.

409 Conflict

The container object may not be deleted.

9.7.8   Example

EXAMPLE   DELETE to the container object URI:

DELETE /MyContainer/ HTTP/1.1

Host: cloud.example.com

The following shows the response.

HTTP/1.1 204 No Content

9.8   Create (POST) a New Data Object using CDMI Content Type

9.8.1   Synopsis

To create a new data object in a specified container where the name of the data object is a server-assigned object identifier, the following request shall be performed:

POST <root URI>/<ContainerName>/

To create a new data object where the data object does not belong to a container and is only accessible by ID (see 5.8), the following request shall be performed:

POST <root URI>/cdmi_objectid/

Where:

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

   <ContainerName> is zero or more intermediate container objects that already exist, with one slash (i.e., "/") between each pair of container object names.

If created in "/cdmi_objectid/", the data object shall be accessible at <root URI>/cdmi_objectid/<objectID>.

If created in a container, the data object shall be accessible as a child of the container with a server-assigned name, and shall also be accessible at <root URI>/cdmi_objectid/<objectID>. 

9.8.2   Delayed Completion of Create

In response to a create operation for a data object, the server may return 202 Accepted to indicate that the object is in the process of being created. This response is useful for long-running operations (e.g., copying a large data object from a source URI). Such a response has the following implications.

   The server shall return a Location header with a URI to the object to be created along with an HTTP status code of 202 Accepted.

   With 202 Accepted, the server implies that the following checks have passed:

   user authorization for creating the object;

   user authorization for read access to any source object for move, copy, serialize, or deserialize; and

   availability of space to create the object or at least enough space to create a URI to report an error.

   A client might not be able to immediately access the created object, e.g., due to delays resulting from the implementation’s use of eventual consistency.

The client performs GET operations to the URI to track the progress of the operation. In response, the server returns two fields in its response message body to indicate progress.

   A mandatory completionStatus text field contains either "Processing", "Complete", or an error string starting with the value "Error".

   An optional percentComplete field contains the percentage that the Accepted POST has completed (0 to 100).

GET does not return any value for the object when completionStatus is not "Complete". When the final result of the create operation is an error, the URI is created with the completionStatus field set to the error message. It is the client's responsibility to delete the URI after the error has been noted.

9.8.3   Capabilities

The following capabilities describe the supported operations that may be performed when creating a new data object by ID in "/cdmi_objectid/":

   Support for the ability to create data objects through this operation is indicated by the presence of the cdmi_post_dataobject_by_ID system capability.

   If the object being created in "/cdmi_objectid/" is a reference, support for that ability is indicated by the presence of the cdmi_create_reference_by_ID system capability.

   If the new data object being created in "/cdmi_objectid/" is a copy of an existing data object, support for the ability to copy is indicated by the presence of the cdmi_copy_dataobject_by_ID system capability.

   If the new data object being created in "/cdmi_objectid/" is the destination of a move, support for the ability to move the data object to "/cdmi_objectid/" is indicated by the presence of the cdmi_object_move_to_ID system capability.

   If the new data object being created in "/cdmi_objectid/" is the destination of a deserialization operation, support for the ability to deserialize the data object is indicated by the presence of the cdmi_deserialize_dataobject_by_ID system capability.

   If the new data object being created in "/cdmi_objectid/" is the destination of a serialize operation, support for the ability to serialize the data object is indicated by the presence of the following system capabilities:

   cdmi_serialize_dataobject_to_ID,

   cdmi_serialize_container_to_ID,

   cdmi_serialize_domain_to_ID, or

   cdmi_serialize_queue_to_ID.

The following capabilities describe the supported operations that may be performed when creating a new data object by ID in a container:

   Support for the ability to create data objects through this operation is indicated by both the presence of the cdmi_post_dataobject and the presence of the cdmi_create_dataobject capability in the specified container object.

   If the object being created in the parent container object is a reference, support for that ability is indicated by the presence of the cdmi_create_reference capability in the parent container object.

   If the new data object is a copy of an existing data object, support for the ability to copy is indicated by the presence of the cdmi_copy_dataobject capability in the parent container object.

   If the new data object is the destination of a move, support for the ability to move the data object is indicated by the presence of the cdmi_move_dataobject capability in the parent container object.

   If the new data object is the destination of a deserialize operation, support for the ability to deserialize the the data object is indicated by the presence of the cdmi_deserialize_dataobject capability in the parent container object.

   If the new data object is the destination of a serialize operation, support for the ability to serialize the source data object is indicated by the presence of the cdmi_serialize_dataobject", "cdmi_serialize_container", "cdmi_serialize_domain", or "cdmi_serialize_queue" capabilities in the parent container object.

9.8.4   Request Headers

The HTTP request headers for creating a new CDMI data object using CDMI content type are shown in Table 49.

Table 49 - Request Headers - Create a New Data Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

Content-Type

Header String

"application/cdmi-object"

Mandatory

X-CDMI-Specification-Version

Header String

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

Mandatory

9.8.5   Request Message Body

The request message body fields for creating a new data object using CDMI content type are shown in Table 50.

Table 50 - Request Message Body - Create a New Data Object using CDMI Content Type

Field Name

Type

Description

Requirement

mimetype

JSON String

MIME type of the data contained within the value field of the data object

   This field may be included when creating by value, deserializing, serializing, copying, and moving a data object.

   This field shall be stored as part of the object.

   If this field is not specified, the value of "text/plain" shall be assigned as the field value.

   This field shall not be included when creating a reference.

   This mimetype value shall be converted to lower case before being stored.

Optional

metadata

JSON Object

Metadata for the data object

   If this field is included when deserializing, serializing, copying, or moving a data object, the value provided in this field shall replace the metadata from the source URI.

   If this field is not included when deserializing, serializing, copying, or moving a data object, the metadata from the source URI shall be used.

   If this field is included when creating a new data object by specifying a value, the value provided in this field shall be used as the metadata.

   If this field is not included when creating a new data object by specifying a value, an empty JSON object (i.e., "{}") shall be assigned as the field value.

   This field shall not be included when referencing a data object.

Optional

domainURI

JSON String

URI of the owning domain

   Any domain may be specified, and the cross_domain privilege is not required (see cdmi_member_privileges in Table 64).

   If not specified, the root domain "/cdmi_domains/" shall be used.

Optional

deserialize

JSON String

URI of a serialized CDMI data object that shall be deserialized to create the new data object

Optionala

serialize

JSON String

URI of a CDMI object that shall be serialized into the new data object

Optionala

copy

JSON String

URI of a CDMI data object or queue that shall be copied into the new data object

Optionala

move

JSON String

URI of a CDMI data object or queue object value that shall be copied into the new data object. The data object or queue object value at the source URI shall be removed upon the successful completion of the copy.

Optionala

reference

JSON String

URI of a CDMI data object that shall be redirected to by a reference. If other fields are supplied when creating a reference, the server shall respond with an HTTP status code of 400 Bad Request.

Optionala

deserializevalue

JSON String

A data object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648.

Optionala

valuetransferencoding

JSON Array of JSON Strings

The value transfer encoding used for the container object value. Two value transfer encodings are defined:

   "utf-8" indicates that the data object contains a valid UTF-8 string, and it shall be transported as a UTF-8 string in the value field.

   "base64" indicates that the data object may contain arbitrary binary sequences, and it shall be transported as a base 64-encoded string in the value field. Setting the contents of the data object value field to any value other than a valid base 64 string shall result in 400 Bad Request error being returned to the client.

This field shall only be included when updating a data object by value. If this field is not specified, the existing value of valuetransferencoding shall be left unchanged.

This field shall be stored as part of the object.

Optional

value

JSON String

JSON-encoded data

   If this field is not included, an empty JSON String (i.e., "") shall be assigned as the field value.

   If the valuetransferencoding field indicates UTF-8 encoding, the value shall be a UTF-8 string escaped using the JSON escaping rules described in RFC 4627.

   If the valuetransferencoding field indicates base 64 encoding, the value shall be first encoded using the base 64 encoding rules described in RFC 4648.

Optionala

aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored. If more than one of these fields is supplied, the server shall respond with a 400 Bad Request error response.

9.8.6   Response Headers

The HTTP response headers for creating a new CDMI data object using CDMI content type are shown in Table 51.

Table 51 - Response Headers - Create a New Data Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-object"

Mandatory

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

Location

Header String

The unique URI for the new data object as assigned by the system. In the absence of file name information from the client the system shall assign the URI in the form: <root URI>/<ContainerName>/<ObjectID>.

Mandatory

9.8.7   Response Message Body

The response message body fields for creating a new CDMI data object using CDMI content type are shown in Table 52.

Table 52 - Response Message Body - Create a New Data Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-object"

Mandatory

objectID

JSON String

Object ID of the object

Mandatory

objectName

JSON String

Name of the object

   For objects in a container, the objectName field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the objectName field does not exist and shall not be returned.

Conditional

parentURI

JSON String

URI for the parent object

   For objects in a container, the parentURI field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentURI field does not exist and shall not be returned.

Appending the objectName to the parentURI shall always produce a valid URI for the object.

Conditional

parentID

JSON String

Object ID of the parent container object

   For objects in a container, the parentID field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentID field does not exist and shall not be returned.

Conditional

domainURI

JSON String

URI of the owning domain

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

completionStatus

JSON String

A string indicating if the object is still in the process of being created, and after the operation is complete, if it was created successfully or an error occurred

The value shall be the string "Processing", the string "Complete", or an error string starting with the value "Error".

Mandatory

percentComplete

JSON String

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer value from 0 through 100.

Optional

mimetype

JSON String

MIME type of the value of the data object

Mandatory

metadata

JSON Object

Metadata for the data object. This field includes any user and data system metadata specified in the request message body metadata field, along with storage system metadata generated by the cloud storage system.

See Clause 16 for a further description of metadata.

Mandatory

9.8.8   Response Status

Table 53 describes the HTTP status codes that occur when creating a new data object using CDMI content type.

Table 53 - HTTP Status Codes - Create a New Data Object using CDMI Content Type

HTTP Status

Description

201 Created

The new data object was created.

202 Accepted

The data object is in the process of being created. The CDMI client should monitor the completionStatus and percentComplete fields to determine the current status of the operation.

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.

409 Conflict

The operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server.

9.8.9   Examples

EXAMPLE 1   POST to the container object URI the data object contents:

POST /MyContainer/ HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "mimetype" : "text/plain",

   "metadata" : {

        

   },

   "value" : "This is the Value of this Data Object"

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

Location: http://cloud.example.com/MyContainer/0000706D0010B84FAD185C425D8B537E

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "0000706D0010B84FAD185C425D8B537E",

   "parentURI" : "/MyContainer/",

   "parentID" : "0000706D0010B84FAD185C425D8B537E",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/dataobject/",

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

        

   }

}

EXAMPLE 2   POST to the object ID URI the data object contents:

POST /cdmi_objectid/ HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "mimetype": "text/plain",

   "domainURI": "/cdmi_domains/MyDomain/",

   "value": "This is the Value of this Data Object"

}

The following shows the response.

HTTP/1.1 201 Created

Location: http://cloud.example.com/cdmi_objectid/0000706D0010B84FAD185C425D8B537E

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID": "0000706D0010B84FAD185C425D8B537E",

   "domainURI": "/cdmi_domains/MyDomain/",

   "capabilitiesURI": "/cdmi_capabilities/dataobject/",

   "completionStatus": "Complete",

   "mimetype": "text/plain",

   "metadata": {

       "cdmi_acl": [

           {

               "acetype": "ALLOW",

               "identifier": "OWNER@",

               "aceflags": "NO_FLAGS",

               "acemask": "ALL_PERMS"

           }

       ]

   }

}

9.9   Create (POST) a New Data Object using a Non-CDMI Content Type

9.9.1   Synopsis

To create a new data object in a specified container where the name of the data object is a server-assigned object identifier, the following request shall be performed:

POST <root URI>/<ContainerName>/

Where:

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

   <ContainerName> is zero or more intermediate container objects that already exist, with one slash (i.e., "/") between each pair of container object names.

The data object shall be accessible as a child of the container with a server-assigned name and shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

9.9.2   Capability

The following capability describes the supported operations that may be performed when creating a new data object:

   Support for the ability to create data objects through this operation is indicated by both the presence of the cdmi_post_dataobject" and the presence of the cdmi_create_dataobject capability in the specified container object.

9.9.3   Request Header

The HTTP request header for creating a new CDMI data object using a non-CDMI content type is shown in Table 54.

Table 54 - Request Header - Create a New Data Object using a Non-CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

The content type of the data to be stored as a data object. The value specified here shall be converted to lower case and stored in the mimetype field of the CDMI data object. If the content type includes the charset parameter as defined in RFC 2246 of "utf-8" (e.g., ";charset=utf-8"), the valuetransferencoding field of the CDMI data object shall be set to "utf-8". Otherwise, the valuetransferencoding field of the CDMI data object shall be set to "base64".

Mandatory

9.9.4   Request Message Body

The message body shall contain the contents (value) of the data object to be created.

9.9.5   Response Header

The HTTP response header for creating a new CDMI data object using a non-CDMI content type is shown in Table 55.

Table 55 - Response Header - Create a New Data Object using a Non-CDMI Content Type

Header

Type

Description

Requirement

Location

Header String

The unique URI for the new data object as assigned by the system. In the absence of file name information from the client the system shall assign the URI in the form: <root URI>/<ContainerName>/<ObjectID>.

Mandatory

9.9.6   Response Message Body

A response message body may be provided as per RFC 2616.

9.9.7   Response Status

Table 56 describes the HTTP status codes that occur when creating a new data object using a non-CDMI content type.

Table 56 - HTTP Status Codes - Create a New Data Object using a Non-CDMI Content Type

HTTP Status

Description

201 Created

The new data object was created.

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.

9.9.8   Examples

EXAMPLE 1   POST to the container object URI the data object contents:

POST /MyContainer/ HTTP/1.1

Host: cloud.example.com

Content-Type: text/plain;charset=utf-8

 

<object contents>

The following shows the response.

HTTP/1.1 201 Created

Location: http://cloud.example.com/MyContainer/0000706D0010B84FAD185C425D8B537E

EXAMPLE 2   POST to the object ID URI the data object contents:

POST /cdmi_objectid/ HTTP/1.1

Host: cloud.example.com

Content-Type: text/plain;charset=utf-8

 

<object contents>

The following shows the response.

HTTP/1.1 201 Created

Location: http://cloud.example.com/cdmi_objectid/0000706D0010B84FAD185C425D8B537E

9.10   Create (POST) a New Queue Object using CDMI Content Type

9.10.1   Synopsis

To create a new queue object (see Clause 11) in a specified container where the name of the queue object is a server-assigned object identifier, the following request shall be performed:

POST <root URI>/<ContainerName>/

To create a new queue object where the queue object does not belong to a container and is only accessible by ID (see 5.8), the following request shall be performed:

POST <root URI>/cdmi_objectid/

Where:

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

   <ContainerName> is zero or more intermediate container objects that already exist, with one slash (i.e., "/") between each pair of container object names.

If created in "/cdmi_objectid/", the queue object shall be accessible at <root URI>/cdmi_objectid/<objectID>.

If created in a container, the queue object shall be accessible as a child of the container with a server-assigned name, and shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

9.10.2   Delayed Completion of Create

On a create operation for a queue object, the server may return a response of 202 Accepted. In this case, the object is in the process of being created. This response is particularly useful for long-running operations, for instance, copying a large number of queue items from a source URI. Such a response has the following implications:

   The server shall return a Location header with a URI to the object to be created along with an HTTP status code of 202 Accepted.

   With 202 Accepted, the server implies that the following checks have passed:

   user authorization for creating the object;

   user authorization for read access to any source object for move, copy, serialize, or deserialize; and

   availability of space to create the object or at least enough space to create a URI to report an error.

   A client might not be able to immediately access the created object, e.g., due to delays resulting from the implementation’s use of eventual consistency.

The client performs GET operations to the URI to track the progress of the operation. In response, the server returns two fields in its response message body to indicate progress.

   A mandatory completionStatus text field contains either "Processing", "Complete", or an error string starting with the value "Error".

   An optional percentComplete field contains the percentage that the accepted POST has completed (0 to 100).

GET does not return any value for the object when completionStatus is not "Complete". When the final result of the create operation is an error, the URI is created with the completionStatus field set to the error message. It is the client's responsibility to delete the URI after the error has been noted.

9.10.3   Capabilities

The following capabilities describe the supported operations that may be performed when creating a new queue object by ID in "/cdmi_objectid/":

   Support for the ability to create queue objects through this operation is indicated by the presence of the cdmi_post_queue_by_ID" system capability.

   If the object being created in "/cdmi_objectid/" is a reference, support for that ability is indicated by the presence of the cdmi_create_reference_by_ID" system capability.

   If the new queue object being created in "/cdmi_objectid/" is a copy of an existing queue object, support for the ability to copy is indicated by the presence of the cdmi_copy_queue_by_ID" system capability.

   If the new queue object being created in "/cdmi_objectid/" is the destination of a move, support for the ability to move the data object to "/cdmi_objectid/" is indicated by the presence of the cdmi_object_move_to_ID" system capability.

   If the new queue object being created in "/cdmi_objectid/" is the destination of a deserialization operation, support for the ability to deserialize the data object is indicated by the presence of the cdmi_deserialize_queue_by_ID" system capability.

The following capabilities describe the supported operations that may be performed when creating a new queue object by ID in a container:

   Support for the ability to create queue objects through this operation is indicated by both the presence of the cdmi_post_queue" and the presence of the cdmi_create_queue capability in the specified container object.

   If the object being created in the parent container object is a reference, support for that ability is indicated by the presence of the cdmi_create_reference capability in the parent container object.

   If the new queue object is a copy of an existing queue object, support for the ability to copy is indicated by the presence of the cdmi_copy_queue capability in the parent container object.

   If the new queue object is the destination of a move, support for the ability to move the queue object is indicated by the presence of the cdmi_move_queue capability in the parent container object.

   If the new queue object is the destination of a deserialize operation, support for the ability to deserialize the the queue object is indicated by the presence of the cdmi_deserialize_queue capability in the parent container object.

9.10.4   Request Headers

The HTTP request headers for creating a new CDMI queue object using CDMI content type are shown in Table 57.

Table 57 - Request Headers - Create a New Queue Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

Content-Type

Header String

"application/cdmi-queue"

Mandatory

X-CDMI- Specification- Version

Header String

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

Mandatory

9.10.5   Request Message Body

The request message body fields for creating a new queue object using CDMI content type are shown in Table 58.

Table 58 - Request Message Body - Create a New Queue Object using CDMI Content Type

Field Name

Type

Description

Requirement

metadata

JSON Object

Metadata for the queue object

   If this field is included when deserializing, serializing, copying, or moving a queue object, the value provided in this field shall replace the metadata from the source URI.

   If this field is not included when deserializing, serializing, copying, or moving a queue object, the metadata from the source URI shall be used.

   If this field is included when creating a new queue object by specifying a value, the value provided in this field shall be used as the metadata.

   If this field is not included when creating a new queue object by specifying a value, an empty JSON object (i.e., "{}") will be assigned as the field value.

   This field shall not be included when referencing a queue object.

Optional

domainURI

JSON String

URI of the owning domain

   Any domain may be specified, and the cross_domain privilege is not required (see cdmi_member_privileges in Table 64).

   If not specified, the root domain "/cdmi_domains/" shall be used.

Optional

deserialize

JSON String

URI of a serialized CDMI data object that will be deserialized to create the new queue object

Optionala

copy

JSON String

URI of a CDMI queue object that will be copied into the new queue object

Optionala

move

JSON String

URI of a CDMI queue object that will be copied into the new queue object. When the copy is successfully completed, the queue object at the source URI is removed.

Optionala

reference

JSON String

URI of a CDMI queue object that shall be redirected to by a reference. If other fields are supplied when creating a reference, the server shall respond with an HTTP status code of 400 Bad Request.

Optionala

deserializevalue

JSON String

A queue object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648.

Optionala

aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored. If more than one of these fields is supplied, the server shall respond with a 400 Bad Request error response.

9.10.6   Response Headers

The response headers for creating a new CDMI queue object using CDMI content type are shown in Table 59.

Table 59 - Response Headers - Create a New CDMI Queue Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-queue"

Mandatory

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

Location

Header String

The unique URI for the new queue object as assigned by the system. In the absence of file name information from the client, the system shall assign the URI in the form: <root URI>/<ContainerName>/<ObjectID>.

Mandatory

9.10.7   Response Message Body

The response message body fields for creating a new CDMI queue object using CDMI content type are shown in Table 60.

Table 60 - Response Message Body - Create a New Queue Object with CDMI Content

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-queue"

Mandatory

objectID

JSON String

Object ID of the object

Mandatory

objectName

JSON String

Name of the object

   For objects in a container, the objectName field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the objectName field does not exist and shall not be returned.

Conditional

parentURI

JSON String

URI for the parent object

   For objects in a container, the parentURI field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentURI field does not exist and shall not be returned.

Appending the objectName to the parentURI shall always produce a valid URI for the object.

Conditional

parentID

JSON String

Object ID of the parent container object

   For objects in a container, the parentID field shall be returned.

   For objects not in a container (objects that are only accessible by ID), the parentID field does not exist and shall not be returned.

Conditional

domainURI

JSON String

URI of the owning domain

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

completionStatus

JSON String

A string indicating if the object is still in the process of being created, and after the operation is complete, if it was created successfully or an error occurred. The value shall be the string "Processing", the string "Complete", or an error string starting with the value "Error".

Mandatory

percentComplete

JSON String

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer value from 0 through 100.

Optional

metadata

JSON Object

Metadata for the queue object. This field includes any user and data system metadata specified in the request message body metadata field, along with storage system metadata generated by the cloud storage system. See Clause 16 for a further description of metadata.

Mandatory

queueValues

JSON String

The range of designators for enqueued values. Every enqueued value shall be assigned a unique, monotonically-incrementing positive integer designator, starting from 0. If no values are enqueued, an empty string shall be returned. If values are enqueued, the lowest designator, followed by a hyphen ("-"), followed by the highest designator shall be returned.

Mandatory

9.10.8   Response Status

Table 61 describes the HTTP status codes that occur when creating a new queue object using CDMI content type.

Table 61 - HTTP Status Codes - Create a New CDMI Queue Object using CDMI Content Type

HTTP Status

Description

201 Created

The new queue object was created.

202 Accepted

The queue object is in the process of being created. The CDMI client should monitor the completionStatus and percentComplete fields to determine the current status of the operation.

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.

409 Conflict

The operation conflicts with a non-CDMI access protocol lock or could cause a state transition error on the server.

9.10.9   Example

EXAMPLE   POST to the container object URI the queue object contents:

POST /MyContainer/ HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-queue

Accept: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

Location: http://cloud.example.com/MyContainer/0000706D0010B84FAD185C425D8B537E

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "0000706D0010B84FAD185C425D8B537E",

   "parentURI" : "/MyContainer/",

   "parentID" : "0000706D0010B84FAD185C425D8B537E",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/queue/",

   "completionStatus" : "Complete",

   "metadata" : {

   },

   "queueValues" : ""

}