Synopsis:
Reads from an existing data object at the specified URI.
• <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 from the response message body.
• <prefix> is a matching prefix that returns all metadata items that start with the prefix value. The object can also be accessed at <root URI>/cdmi_objectid/<objectID>.
Capabilities:
The following capabilities describe the supported operations that can 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. 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.
Request Headers: N/A
Request Message Body: N/A
GET <root URI>/<ContainerName>/<DataObjectName>
GET <root URI>/<ContainerName>/<DataObjectName>?<fieldname> GET <root URI>/<ContainerName>/<DataObjectName>?metadata:<prefix>
Response Headers:
Response Message Body:
• If no fields were specified in the request or the value field was specified in the request, the response message body shall be the contents of the data object's value field.
• If a field other than the value field was specified in the request, the value of that specified field shall be returned in JSON format.
• Requesting an optional field that is not present results in an HTTP status code of 404 Not Found. • Requesting an undefined field results in an HTTP status codeof 400 Bad Request .
Response Status:
Example Request:
GET to the data object URI to read the value of the data object
The response looks like:
Header Type Value Mandatory/Optional
Content-Type Header
String
If a field was not specified, or the value field was specified, the content-type returned shall be the "mimetype" field in the data object.
If a non-value field was specified, the content-type shall be "text/json"
Mandatory
Location Header
String
The server shall respond with the URI that the reference points to if the object is a reference.
Mandatory
HTTP Status Description
200 OK Data object contents in response
204 No Content Data object may not be complete, retry later
206 Partial Content A requested range of the data object content was returned in response
302 Found The URI is a reference to another URI
400 Bad Request Invalid parameter of field names in the request 401 Unauthenticated Incorrect or missing authentication credentials
403 Unauthorized Client lacks the proper authorization to perform this request
404 Not Found A data object was not found at the specified URI, or a requested field within the data object was not found.
GET /MyContainer/MyDataObject.txt HTTP/1.1 Host: cloud.example.com
HTTP/1.1 200 OK
Content-Type: text/plain Content-Length: 37
Example Request:
GET to the data object URI to read the mimetype field of the data object
The response looks like:
Example Request:
GET to the data object URI to read the first ten bytes of the value of the data object
The response looks like:
8.6
Update a Data Object (CDMI Content Type)
Synopsis:
Updates an existing data object at the specified URI.
• <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 field.
The object can also be accessed at <root URI>/cdmi_objectid/<objectID>, and an update shall not result in a change to the Object ID.
Capabilities:
The following capabilities describe the supported operations that can be performed when updating an GET /MyContainer/MyDataObject.txt?mimetype HTTP/1.1 Host: cloud.example.com HTTP/1.1 200 OK Content-Type: text/json { "mimetype" : "text/plain" } GET /MyContainer/MyDataObject.txt HTTP/1.1 Host: cloud.example.com Range: bytes=0-10 HTTP/1.1 206 Partial Content Content-Type: text/plain Content-Range: bytes 0-10 Content-Length: 11 This is the
PUT <root URI>/<ContainerName>/<DataObjectName>
PUT <root URI>/<ContainerName>/<DataObjectName>?metadata PUT <root URI>/<ContainerName>/<DataObjectName>?value
• 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 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.
Request Headers:
Request Message Body:
Header Type Value Mandatory/Optional
Accept Header String "application/vnd.org.snia.cdmi.dataobject+json" Mandatory Content-Type Header String "application/vnd.org.snia.cdmi.dataobject+json" Mandatory X-CDMI- Specification- Version Header String
A comma separated list of versions supported by the client, for example, "1.0, 1.5, 2.0".
Mandatory
X-CDMI- MustExist
Header String
"true". Fail updates if the object does not exist. If this header element exists and is set to "true", it is an error for the object to not already exist.
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 will 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 will change the "completionStatus" field back to
"Complete".
Optional
Name Type Description Mandatory/Optional
mimetype JSON
String
Mime type of the data contained within the value field of the data object. If present, this replaces the existing mimetype.
Optional
metadata JSON
Object
Metadata for the data object. If present, this replaces the existing metadata. See Chapter 16, “Metadata” for a further description of metadata.
Optional
domainURI JSON
String
URI of the owning domain.
• If different from the parent domain, the user must have the "cross_domain" privilege. • If not specified, the parent domain will be
used.
Response Headers:
Response Message Body: N/A
Response Status:
value JSON
String
This is the new data for the object. If present, this replaces the existing value.
• If a value range was specified in the request, the new data is inserted at the location specified by the range. Any resulting gaps between ranges should be treated as all zeros, and included when calculating the size of the value.
• Binary data must be escaped as per the JSON escaping rules described in RFC4627.
Optional
Header Type Value Mandatory/Optional
Location Header
String
The server shall respond with the URI that the reference points to if the object is a reference.
Mandatory
HTTP Status Description
200 OK New metadata and/or content accepted
302 Found The URI is a reference to another URI
400 Bad Request Invalid parameter of field names in the request 401 Unauthenticated Incorrect or missing authentication credentials
403 Unauthorized Client lacks the proper authorization to perform this request
404 Not Found An update was attempted on an object that does not exist, and the X-CDMI- MustExist header element was set to "true".
409 Conflict The operation conflicts with a non-CDMI access protocol lock, or could cause a state transition error on the server.
Example Request:
PUT to the data object URI to set new field values
The response looks like:
Example Request:
PUT to the data object URI to set a new mimetype
The response looks like:
Example Request:
PUT to the data object URI to update a range of the value
The response looks like:
PUT /MyContainer/MyDataObject.txt HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 { "mimetype" : "text/plain", "metadata" : { },
"value" : "This is the Value of this Data Object" } HTTP/1.1 200 OK PUT /MyContainer/MyDataObject.txt?mimetype HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 { "mimetype" : "text/plain" } HTTP/1.1 200 OK PUT /MyContainer/MyDataObject.txt?value:21-24 HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.dataobject+json Content-Type: application/vnd.org.snia.cdmi.dataobject+json X-CDMI-Specification-Version: 1.0 { "value" : "that" } HTTP/1.1 200 OK