8    Data Object Resource Operations

8.1   Overview

Data objects are the fundamental storage component within CDMI™ and are analogous to files within a file system. Each data object has a set of well-defined fields that include:

   a single value; and

   optional metadata that is generated by the cloud storage system and specified by the cloud user.

Data objects are addressed in CDMI in two ways:

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

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

Every data object has a single, globally-unique object identifier (ID) that remains constant for the life of the object. Each data object shall have one or more URI addresses that allow the object to be accessed. 

Every data object has a parent object from which the data object inherits data system metadata that is not explicitly specified in the data object itself. Thus, the "budget.xls" data object stored at the following URI would inherit data system metadata from its parent container, "finance":

http://cloud.example.com/finance/budget.xls

Individual fields within a data object may be accessed by specifying the field name after a question mark "?" that is appended to the end of the data object URI. Thus, the following URI returns the value field in the response message body:

http://cloud.example.com/dataobject?value

The encoding of the data transported in the data object value field depends on the data object valuetransferencoding field.

   If the value transfer encoding of the object is set to "utf-8", the data stored in the value of the data object shall be a valid UTF-8 string and shall be transported as a UTF-8 string in the value field.

   If the value transfer encoding of the object is set to "base64", the data stored in the value of the data object can contain arbitrary binary sequences, and it shall be transported as a base 64-encoded string in the value field.

Specific ranges of the value of a data object may be accessed by specifying a byte range after the value field name. Thus, the following URI returns the first thousand bytes in the value field:

http://cloud.example.com/dataobject?value:0-999

Because a byte range of a UTF-8 string is often not a valid UTF-8 string, the response to a range request shall always be transported in the value field as a base 64-encoded string. Likewise, when updating a range of bytes within the value of a data object, the contents of the value field shall be transported as a base 64-encoded string.

Byte ranges are specified as single inclusive byte ranges as per Section 14.35.1 of RFC 2616.

A list of unique fields, separated by a semicolon ";" may be specified, allowing multiple fields to be accessed in a single request. Thus, the following URI returns the value and metadata fields in the response message body:

http://cloud.example.com/dataobject?value;metadata

When a client provides fields that are not defined in this international standard or deserializes an object containing fields that are not defined in this international standard, these fields shall be stored as part of the object but shall not be interpreted.

8.1.1   Data Object Metadata

Data object metadata may also include arbitrary user-supplied metadata and data system metadata, as specified in Clause 16. Metadata shall be stored as a valid UTF-8 string. Binary data stored in user metadata shall be first encoded such that it can be contained in a UTF-8 string, with the use of base 64 encoding recommended.

8.1.2   Data Object Consistency

Writing to a data object is an atomic operation.

   If a client reads a data object simultaneously with a write to that same data object, the reading client shall get either the old version or the new version, but not a mixture of both.

   If a write is terminated due to errors, the contents of the data object shall be as if the write never occurred (i.e., writes are atomic in the face of errors).

The timestamp returned in the response to a write indicates whether the write is the newest (i.e., the write whose data is returned to subsequent reads, until another write is processed). If the timestamp returned for one write shows a more recent time than the timestamp for another write, then the write with the new timestamp shall be the one whose data is currently stored in the data object wherever the two writes overlap.

Range writes can result in a gap in an object value that have had no data written to them. Reading from a gap in a data object value shall return zero for each byte read.

Implementations of this international standard shall provide the atomicity features described in this subclause for data objects that are accessed via CDMI. The atomicity properties of data objects that are accessed by protocols other than CDMI are outside the scope of this international standard.

8.1.3   Data 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 data objects, the valuerange and value fields shall appear last and in that order.

8.2   Create a Data Object Using CDMI Content Type

8.2.1   Synopsis

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

PUT <root URI>/<ContainerName>/<DataObjectName>

To create a new data object by ID, see 9.9.

Where:

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

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

   <DataObjectName> is the name specified for the data object to be created.

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

8.2.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 of the operation that has completed
(0 to 100).

GET shall not return any value for the data object when completionStatus is not "Complete". If 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.

8.2.3   Capabilities

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

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

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

   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.

   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.

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

   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 capability in the parent container.

8.2.4   Request Headers

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

Table 7 - Request Headers for Creating a CDMI 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

X-CDMI-Partial

Header String

"true". Indicates that the newly created object is part of a series of writes and the value has not yet been fully populated. If X-CDMI-Partial is present, the completionStatus field in the Response Body shall be set to "Processing".

Optional

8.2.5   Request Message Body

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

Table 8 - Request Message Body - Create a 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 or when 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 MIME type 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

   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 domain of the parent container 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 an existing local or remote CDMI data object (source URI) that shall be relocated to the URI specified in the PUT. The contents of the object, including the object ID, shall be preserved by a move, and the data object at the source URI shall be removed after the data object at the destination has been successfully created.

If there are insufficient permissions to read the data object at the source URI, write the data object at the destination URI, or delete the data object 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 data object that shall be redirected to by a reference. If any 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 String

The value transfer encoding used for the data 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 error 400 Bad Request being returned to the client.

This field shall only be included when creating a data object by value. If not specified by the client, the server shall set the valuetransferencoding field to "utf-8".

This field shall be stored as part of the object.

Optional

value

JSON String

The data object value

   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.

8.2.6   Response Headers

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

Table 9 - Response Headers - Create a 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

8.2.7   Response Message Body

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

 

Table 10 - Response Message Body - Create a 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

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 that shall indicate the status of the data object creation operation using one of the following values

   "Processing" indicates that the data object is still in the process of being created.

   "Completed" indicates that the data object has been successfully created.

   A string that begins with "Error" indicates that an error prevented creation of the data object.

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

8.2.8   Response Status

The HTTP status codes that occur when creating a data object using CDMI content type are described in Table 11.

Table 11 - HTTP Status Codes - Create a 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.

8.2.9   Examples

EXAMPLE 1   PUT to the container URI the data object name and contents:

PUT /MyContainer/MyDataObject.txt 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

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "MyDataObject.txt",

   "parentURI" : "/MyContainer/",

    "parentID" : "00007E7F00102E230ED82694DAA975D2",

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

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

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

        "cdmi_size" : "37"

   }

}

EXAMPLE 2   PUT to the container URI the data object name and binary contents:

PUT /MyContainer/MyDataObject.txt 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" : { },

  "valuetransferencoding" : "base64"

  "value" : "VGhpcyBpcyB0aGUgVmFsdWUgb2YgdGhpcyBEYXRhIE9iamVjdA=="

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

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

  "objectID": "0000706D0010374085EF1A5C7018D774",

  "objectName": "MyDataObject.txt",

  "parentURI": "/MyContainer/",

   "parentID" : "00007E7F00102E230ED82694DAA975D2",

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

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

  "completionStatus": "Complete",

  "mimetype": "text/plain",

  "metadata": {

      "cdmi_size": "37"

  }

}

8.3   Create a Data Object using a Non-CDMI Content Type

8.3.1   Synopsis

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

PUT <root URI>/<ContainerName>/<DataObjectName>

Where:

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

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

   <DataObjectName> is the name specified for the data object to be created.

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

8.3.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 a new data object is indicated by the presence of the cdmi_create_dataobject capability in the parent container.

8.3.3   Request Headers

The HTTP request headers for creating a CDMI data object using a non-CDMI content type are shown in Table 12.

Table 12 - Request Headers - Create a CDMI 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 used as the mimetype field of the CDMI data object. If the content type includes the charset parameter as defined in RFC 2046 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

X-CDMI-Partial

Header String

"true". Indicates that the newly created object is part of a series of writes and has not yet been fully created. When set, the completionStatus field shall be set to "Processing".

Optional

8.3.4   Request Message Body

The request message body contains the data to be stored in the value of the data object.

8.3.5   Response Headers

No response headers are specified.

8.3.6   Response Message Body

No response message body fields are specified.

8.3.7   Response Status

The HTTP status codes that occur when creating a data object using a non-CDMI content type are described in Table 13.

Table 13 - HTTP Status Codes - Create a 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.

409 Conflict

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

8.3.8   Example

EXAMPLE   PUT to the container URI the data object name and contents:

PUT /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

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

Content-Length: 37

 

This is the Value of this Data Object

The following shows the response.

HTTP/1.1 201 Created

8.4   Read a Data Object using CDMI Content Type

8.4.1   Synopsis

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

GET <root URI>/<ContainerName>/<DataObjectName>

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

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

GET <root URI>/<ContainerName>/<DataObjectName>?value:<range>;...

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

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be read from.

   <fieldname> is the name of a field.

   <range> is a byte range of the data object value to be returned in the value field.<prefix> is a matching prefix that returns all metadata items that start with the prefix value.

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

8.4.2   Capabilities

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

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

   Support for the ability to read the value of an existing data object is indicated by the presence of the cdmi_read_value capability in the specified object.

   Support for the ability to read the value of an existing data object in specific byte ranges is indicated by the presence of the cdmi_read_value_range capability in the specified object.

8.4.3   Request Headers

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

Table 14 - Request Headers - Read a CDMI 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

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

8.4.4   Request Message Body

A request message body shall not be provided.

8.4.5   Response Headers

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

Table 15 - Response Headers - Read a CDMI Data 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-object"

Mandatory

Location

Header String

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

Conditional

8.4.6   Response Message Body

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

Table 16 - Response Message Body - Read a 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

valuerange

JSON String

The range of bytes of the data object to be returned in the value field

   If a specific value range has been requested, the value range field shall correspond to the bytes requested. If the request extends beyond the end of the value, the value range field shall indicate the smaller byte range returned.

   If the object value has gaps (due to PUTs with non-contiguous value ranges), the value range will indicate the range to the first gap in the object value.

   The cdmi_size storage system metadata of the data object shall always indicate the complete size of the object, including zero-filled gaps.

Mandatory

valuetransferencoding

JSON Array of JSON Strings

The value transfer encoding used for the data 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.

Mandatory

value

JSON String

The data object value

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

   If the valuetransferencoding field indicates base 64 encoding, the value field shall contain a base 64-encoded string as described in RFC 4648.

   The value field shall only be provided when the completionStatus field contains "Complete".

   When reading a value, zeros shall be returned for any gaps resulting from non-contiguous writes.

Conditional

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.

8.4.7   Response Status

The HTTP status codes that occur when reading a data object using CDMI content type are described in Table 17.

Table 17 - HTTP Status Codes - Read a CDMI Data Object using CDMI Content Type

HTTP Status

Description

200 OK

The data object content was returned in the response.

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.

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.

8.4.8   Examples

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

GET /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

X-CDMI-Specification-Version: 1.0.2

Content-Type: application/cdmi-object

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "MyDataObject.txt",

   "parentURI" : "/MyContainer/",

    "parentID" : "00007E7F00102E230ED82694DAA975D2",

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

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

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

        "cdmi_size" : "37"

   },

   "valuerange" : "0-36",

   "valuetransferencoding" : "utf-8",

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

}

EXAMPLE 2   GET to the data object URI by ID to read all fields of the data object:

GET /cdmi_objectid/0000706D0010B84FAD185C425D8B537E

HTTP/1.1 Host: cloud.example.com

Accept: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID" : "0000706D0010B84FAD185C425D8B537E",

   "objectName" : "MyDataObject.txt",

   "parentURI" : "/MyContainer/",

    "parentID" : "00007E7F00102E230ED82694DAA975D2",

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

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

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

        "cdmi_size" : "37"

   },

   "valuetransferencoding" : "utf-8",

   "valuerange" : "0-36",

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

}

EXAMPLE 3   GET to the data object URI to read the value and mimetype fields of the data object:

GET /MyContainer/MyDataObject.txt?value;mimetype HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "mimetype" : "text/plain"

}

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

GET /MyContainer/MyDataObject.txt?valuerange;value:0-10 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "valuerange" : "0-10",

   "value" : "VGhpcyBpcyB0aGU="

}

8.5   Read a Data Object using a Non-CDMI Content Type

8.5.1   Synopsis

To read the value of an existing data object, the following request shall be performed:

GET <root URI>/<ContainerName>/<DataObjectName>

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be read from.

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

8.5.2   Capabilities

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

   Support for the ability to read the value of an existing data object is indicated by the presence of the cdmi_read_value capability in the specified object. Any read from a specific byte location not previously written to by a create or update operation shall return zero for the byte value.

   Support for the ability to read the value of an existing data object in specific byte ranges is indicated by the presence of the cdmi_read_value_range capability in the specified object. Any read from a specific byte location within the value range specified not previously written to by a create or update operation shall return zero for the byte value.

8.5.3   Request Header

The HTTP request header for reading a CDMI data object using a non-CDMI content type is shown in Table 18.

Table 18 - Request Header - Read a CDMI Data Object using a Non-CDMI Content Type

Header

Type

Description

Requirement

Range

Header String

A valid ranges-specifier (see RFC 2616 Section 14.35.1)

Optional

8.5.4   Request Message Body

A request message body shall not be provided.

8.5.5   Response Headers

The HTTP response headers for reading a data object using a non-CDMI content type are shown in Table 19.

Table 19 - Response Headers - Read a CDMI Data Object using a Non-CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

The content type returned shall be the mimetype field in the data object.

Mandatory

Location

Header String

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

Conditional

8.5.6   Response Message Body

When reading a data object using a non-CDMI content type, the following applies:

   The response message body shall be the contents of the data object's value field.

   When reading a value, zeros shall be returned for any gaps resulting from non-contiguous writes.

8.5.7   Response Status

The HTTP status codes that occur when reading a data object using a non-CDMI content type are described in Table 20.

Table 20 - HTTP Status Codes - Read a CDMI Data Object using a Non-CDMI Content Type

HTTP Status

Description

200 OK

The data object content was returned in the response.

206 Partial Content

A requested range of the data object content was returned in the response.

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, or a requested field within the resource was not found.

8.5.8   Examples

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

GET /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

The following shows the response.

HTTP/1.1 200 OK

Content-Type: text/plain

Content-Length: 37

 

This is the Value of this Data Object

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

GET /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Range: bytes=0-10

The following shows the response.

HTTP/1.1 206 Partial Content

Content-Type: text/plain

Content-Range: bytes 0-10/37

Content-Length: 11

 

This is the

8.6   Update a Data Object using CDMI Content Type

8.6.1   Synopsis

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

PUT <root URI>/<ContainerName>/<DataObjectName>

To update the value of an existing data object, the following request shall be performed:

PUT <root URI>/<ContainerName>/<DataObjectName>?value:<range>

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

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

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be updated.

   <range> is a byte range within the data object value to be updated.

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

8.6.2   Capabilities

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

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

   Support for the ability to modify the value of an existing data object and/or MIME type is indicated by the presence of the cdmi_modify_value capability in the specified object.

   Support for the ability to modify the value of an existing data object in specified byte ranges is indicated by the presence of the cdmi_modify_value_range capability in the specified object.

8.6.3   Request Headers

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

Table 21 - Request Headers - Update a CDMI Data Object using CDMI Content Type

Header

Type

Description

Requirement

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

X-CDMI-Partial

Header String

"true". Indicates that the object is in the process of being updated, and has not yet been fully updated. When set, the completionStatus field shall be set to "Processing".

If the completionStatus field had previously been set to "Processing" by including this header in a create or update, the next update without this field shall change the completionStatus field back to "Complete".

Optional

8.6.4   Request Message Body

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

Table 22 - Request Message Body - Update a CDMI 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. If present, this replaces the existing MIME type.

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

   This field shall be stored as part of the object.

   If this field is not specified, the existing value of the mimetype field shall be left unchanged.

   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 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 existing domain shall be preserved.

Optional

deserialize

JSON String

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

Optionala

copy

JSON String

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

Optionala

deserializevalue

JSON String

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

Optionala

valuetransferencoding

JSON Array of JSON Strings

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

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

   "base64" indicates that the data object may contain arbitrary binary sequences, and 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 error 400 Bad Request 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 the valuetransferencoding field shall be left unchanged.

This field shall be stored as part of the object.

Optional

value

JSON String

This is the new data for the object. If present, this replaces the existing 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.

   If a value range was specified in the request, the new data shall be inserted at the location specified by the range. Any resulting gaps between ranges shall be treated as if zeros had been written and shall be included when calculating the size of the value. When storing a range, the value shall be encoded using base 64, and the valuetransferencoding field shall be set to "base64".

Optional

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.

8.6.5   Response Header

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

Table 23 - Response Header - Update a CDMI Data 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

8.6.6   Response Message Body

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

8.6.7   Response Status

The HTTP status codes that occur when updating a data object using CDMI content type are described in Table 24.

Table 24 - HTTP Status Codes - Update a CDMI Data Object using CDMI Content Type

HTTP Status

Description

204 No Content

The operation was successful; no data was returned.

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.

8.6.8   Examples

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

PUT /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "mimetype" : "text/plain",

   "metadata" : {

       "colour" : "blue",

        "length" : "10"

   },

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

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 2   PUT to the data object URI to set a new MIME type:

PUT /MyContainer/MyDataObject.txt?mimetype HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "mimetype" : "text/plain"

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 3   PUT to the data object URI to update a range of the value:

PUT /MyContainer/MyDataObject.txt?value:21-24 HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "value" : "dGhhdA=="

}

The following shows the response.

HTTP/1.1 204 No Content

When updating a value without specifying a value transfer encoding, the client must be aware of the current value transfer encoding of the object. If a client sends a value containing a UTF-8 string to update an existing object with a valuetransferencoding value of "base64", this shall result in an error being returned. If a client sends a value containing a base 64 string to update an existing object with a valuetransferencoding value of "utf-8", this shall not generate an error, but results in the literal base 64 character sequence being stored in the data object instead of the expected data encoded in the base 64 string.

EXAMPLE 4   PUT to the data object URI to replace all metadata with new metadata:

PUT /MyContainer/MyDataObject.txt?metadata HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

       "colour" : "red",

       "number" : "7"

   }

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 5   PUT to the data object URI to add a new metadata item while preserving existing metadata:

PUT /MyContainer/MyDataObject.txt?metadata:shape HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

       "shape" : "round"

   }

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 6   PUT to the data object URI to replace just one metadata item with a new value:

PUT /MyContainer/MyDataObject.txt?metadata:colour HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

       "colour" : "green"

   }

}

The following shows the response.

HTTP/1.1 204 No Content

8.7   Update a Data Object using a Non-CDMI Content Type

8.7.1   Synopsis

To update the value of an existing data object, the following request shall be performed:

PUT <root URI>/<ContainerName>/<DataObjectName>

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be updated.

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

8.7.2   Capabilities

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

   Support for the ability to modify the value of an existing data object and/or MIME type is indicated by the presence of the cdmi_modify_value capability in the specified object.

   Support for the ability to modify the value of an existing data object in specified byte ranges is indicated by the presence of the cdmi_modify_value_range capability in the specified object.

8.7.3   Request Headers

The HTTP request headers for updating a CDMI data object using a non-CDMI content type are shown in Table 25.

Table 25 - Request Headers - Update a CDMI 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 used in the mimetype field of the CDMI data object.

Mandatory

Content-Range

Header String

A valid ranges-specifier (see RFC 2616 Section 14.35.1)

Optional

X-CDMI-Partial

Header String

"true". Indicates that the object is in the process of being updated and has not yet been fully updated. When set, the completionStatus field shall be set to "Processing".

If the completionStatus field had previously been set to "Processing" by including this header in a create or update, the next update without this field shall change the completionStatus field back to "Complete".

Optional

8.7.4   Request Message Body

The request message body contains the data to be stored in the value of the data object.

8.7.5   Response Header

The HTTP response header for updating a data object using a non-CDMI content type is shown in Table 26.

Table 26 - Response Header - Update a CDMI Data Object using a Non-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

8.7.6   Response Message Body

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

8.7.7   Response Status

the HTTP status codes that occur when updating a data object using a non-CDMI content type are described in Table 27.

Table 27 - HTTP Status Codes - Update a CDMI Data Object using a Non-CDMI Content Type

HTTP Status

Description

204 No Content

The operation was successful; no data was returned.

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.

8.7.8   Examples

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

PUT /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Content-Type: text/plain

Content-Length: 37

 

This is the value of this data object

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 2   PUT to the data object URI to update four bytes within the value of the data object:

PUT /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Content-Range: bytes 21-24/37

Content-Type: text/plain

Content-Length: 4

 

that

The following shows the response.

HTTP/1.1 204 No Content

8.8   Delete a Data Object using CDMI Content Type

8.8.1   Synopsis

To delete an existing data object, the following request shall be performed:

DELETE <root URI>/<ContainerName>/<DataObjectName>

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be deleted.

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

8.8.2   Capability

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

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

8.8.3   Request Header

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

Table 28 - Request Header - Delete a CDMI Data 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

8.8.4   Request Message Body

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

8.8.5   Response Headers

Response headers may be provided as per RFC 2616.

8.8.6   Response Message Body

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

8.8.7   Response Status

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

Table 29 - HTTP Status Codes - Delete a CDMI Data Object using CDMI Content Type

HTTP Status

Description

204 No Content

The data 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 operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server or the data object may not be deleted.

8.8.8   Example

EXAMPLE   DELETE to the data object URI:

DELETE /MyContainer/MyDataObject.txt 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

8.9   Delete a Data Object using a Non-CDMI Content Type

8.9.1   Synopsis

To delete an existing data object, the following request shall be performed:

DELETE <root URI>/<ContainerName>/<DataObjectName>

Where:

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

   <ContainerName> is zero or more intermediate containers.

   <DataObjectName> is the name of the data object to be deleted.

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

8.9.2   Capability

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

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

8.9.3   Request Headers

Request headers may be provided as per RFC 2616.

8.9.4   Request Message Body

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

8.9.5   Response Headers

Response headers may be provided as per RFC 2616.

8.9.6   Response Message Body

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

8.9.7   Response Status

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

Table 30 - HTTP Status Codes - Delete a CDMI Data Object using a Non-CDMI Content Type

HTTP Status

Description

204 No Content

The data 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 operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server or the data object may not be deleted.

8.9.8   Example

EXAMPLE   DELETE to the data object URI:

DELETE /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

The following shows the response.

HTTP/1.1 204 No Content