9 Container Object Resource Operations
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 URI (e.g., http://cloud.example.com/container/); and
• by object ID (e.g., http://cloud.example.com/cdmi_objectid/0000706D0010B84FAD185C425D8B537E.
The first example addresses the container object by URI, and the second addresses the container object by CDMI object ID. Every container object has a single, globally-unique object identifier (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.
Containers may also be nested, as follows:
http://cloud.example.com/container/sub-container/
A container object may have a parent object. In this case, the container object inherits data system metadata from its parent object.
EXAMPLE 1 The "sub-container" container object may inherit its data system metadata from the parent container object "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 filesystem, then the filesystem may make the CDMI metadata accessible via filesystem-specific mechanisms. As files and directories are created by the filesystem, they become visible through the CDMI interface acting as a data path. The mapping between filesystem 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 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 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 body:
http://cloud.example.com/container/?children;metadata
When a client provides or includes deserialization fields that are not defined in this specification, these fields shall be stored as part of the object.
The following optional data system metadata may be provided (see Table 29).
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 specification defines reserved container names that shall not be used when creating new containers. These container names are reserved for use by this specification, 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 the specification, 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 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
The following HTTP PUT creates a new container object at the specified URI.
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 an object ID along with 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.
• Future accesses to the URI created (or the object ID) shall succeed except when delays occur due to an 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 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.
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.
The HTTP request headers for creating a CDMI container object using CDMI content type are shown in Table 30.
Header |
Type |
Description |
Requirement |
Accept |
Header String |
"application/cdmi-container" |
Mandatory |
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.1, 1.5, 2.0" |
Mandatory |
The request message body fields for creating a container object using CDMI content type are shown in Table 31.
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 pointed to by a reference. If other fields from this table are supplied when creating a reference, the server shall respond with a 400 Bad Request error response. |
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. |
|||
The HTTP response headers for creating a CDMI container object using CDMI content type are shown in Table 32.
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.1". 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 |
The response message body fields for creating a CDMI container object using CDMI content type are shown in Table 33.
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 shall not be returned. |
Mandatory |
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 shall not be returned. 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 • 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 shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object. |
Mandatory |
domainURI |
JSON String |
URI of the owning domain |
Mandatory |
capabilitiesURI |
JSON String |
URI to the capabilities for the object The capabilities URI returned is based on the object type and requested data system metadata fields. |
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 |
The value shall be an integer numeric 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 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 range of the children returned in the children field |
Mandatory |
children |
JSON Array |
Names of the children objects in the container object. Child container objects end with "/". |
Mandatory |
aReturned only if present. |
|||
Table 34 describes the HTTP status codes that occur when creating a container object using CDMI content type.
HTTP Status |
Description |
201 Created |
New container object was created. |
202 Accepted |
Container is in the process of being created. The CDMI client should monitor completionStatus and percentComplete fields to determine the current status of the operation. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A resource was not found at the specified URI. |
409 Conflict |
The container object name already exists. |
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.1
{ "metadata" : {
}, "exports" : { "OCCI/iSCSI" : { "identifier" : "0000706D0010B84FAD185C425D8B537E", "permissions" : "00007E7F00104EB781F900791C70106C" }, "Network/NFSv4" : { "identifier" : "/users", "permissions" : "domain" } } } |
The following shows the response.
|
Content-Type: application/cdmi-container X-CDMI-Specification-Version: 1.0.1
{ "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
The following HTTP PUT creates a new container object at the specified URI.
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.
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.
No request headers are specified by this international standard.
No request message body fields are specified by this international standard.
No response headers are specified by this international standard.
No response message body fields are specified by this international standard.
Table 35 describes the HTTP status codes that occur when creating a container object using a non-CDMI content type.
HTTP Status |
Description |
201 Created |
New container object was created. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
409 Conflict |
The container object name already exists. |
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
The following HTTP GET reads from an existing container object at the specified URI.
GET <root URI>/<ContainerName>/<TheContainerName>/ 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>.
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.
The HTTP request headers for reading a CDMI container object using CDMI content type are shown in Table 36.
Header |
Type |
Description |
Requirement |
Accept |
Header String |
"application/cdmi-container". This header shall contain a list of one or more of the five CDMI MIME types (see RFC 6208). |
Mandatory |
X-CDMI-Specification-Version |
Header String |
A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0" |
Mandatory |
No request message body fields are specified by this international standard.
The HTTP response headers for reading a CDMI container object using CDMI content type are shown in Table 37.
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.1". 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 points to if the object is a reference. |
Mandatory |
The response message body fields for reading a CDMI container object using CDMI content type are shown in Table 38.
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 shall not be returned. |
Mandatory |
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 shall not be returned. 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 • 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 shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object. |
Mandatory |
domainURI |
JSON String |
URI of the owning domain |
Mandatory |
capabilitiesURI |
JSON String |
URI to the capabilities for the object The capabilities URI returned is based on the object type and requested data system metadata fields. |
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 |
The value shall be an integer numeric 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 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 |
Optionala |
childrenrange |
JSON String |
The range of the children returned in the children field |
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.
Table 39 describes the HTTP status codes that occur when reading a container object using CDMI content type.
HTTP Status |
Description |
200 OK |
Metadata for the container object is provided in the message body. |
302 Found |
The URI is a reference to another URI. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A 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. |
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.1 |
:
The following shows the response.
HTTP/1.1 200 OK Content-Type: application/cdmi-container X-CDMI-Specification-Version: 1.0.1
{ "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" : "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.1 |
:
The following shows the response.
HTTP/1.1 200 OK Content-Type: application/cdmi-container X-CDMI-Specification-Version: 1.0.1
{ "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.1 |
:
The following shows the response.
HTTP/1.1 200 OK Content-Type: application/cdmi-container X-CDMI-Specification-Version: 1.0.1
{ "childrenrange" : "0-2", "children" : [ "red", "green", "yellow" ] } |
9.5 Read a Container Object using a Non-CDMI Content Type
The following HTTP GET reads from an existing container object at the specified URI.
GET <root URI>/<ContainerName>/<TheContainerName>/?<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>.
CDMI does not define the format for a GET of a container object when fields are not being requested.
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.
• 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.
No request headers are specified by this international standard.
No request message body fields are specified by this international standard.
The HTTP response headers for reading a CDMI container object using a non-CDMI content type are shown in Table 40.
Header |
Type |
Description |
Requirement |
Content-Type |
Header String |
"application/json” |
Mandatory |
Location |
Header String |
The server shall respond with the URI that the reference points to if the object is a reference. |
Mandatory |
The value of the specified field shall be returned in JSON format.
Table 41 describes the HTTP status codes that occur when reading a container object using a non-CDMI content type.
HTTP Status |
Description |
200 OK |
Metadata for the container object is provided in the message body. |
302 Found |
The URI is a reference to another URI. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A resource was not found at the specified URI. |
• Requesting an optional field that is not present shall result in a 404 Not Found HTTP status code.
• Requesting an undefined field shall result in a 400 Bad Request HTTP status code.
EXAMPLE 1 GET to the container object URI to read parentURI of the container object
GET /MyContainer/?parentURI HTTP/1.1 Host: cloud.example.com |
:
The following shows the response.
HTTP/1.1 200 OK Content-Type: application/json
{ "parentURI" : "/" } |
EXAMPLE 2 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 |
:
The following shows the response.
HTTP/1.1 200 OK Content-Type: application/json
{ "childrenrange" : "0-2", "children" : [ "red", "green", "yellow" ] } |
9.6 Update a Container Object using CDMI Content Type
The following HTTP PUT updates an existing container object at the specified URI.
PUT <root URI>/<ContainerName>/<TheContainerName>/ 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.
Delayed Completion of Snapshot
If the Request Message Body contains a snapshot field, the server may return a response 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.
• Future accesses to the snapshot URI created (or the object ID) shall succeed except when delays occur due to an 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 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.
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.
The HTTP request headers for updating a CDMI container object using CDMI content type are shown in Table 42.
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.1, 1.5, 2.0" |
Mandatory |
The request message body fields for updating a container object using CDMI content type are shown in Table 43.
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. If a snapshot is added or altered, 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 must 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 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. |
|||
The HTTP response header for updating a CDMI container object using CDMI content type is shown in Table 44.
Header |
Type |
Description |
Requirement |
Location |
Header String |
The server shall respond with the URI that the reference points to if the object is a reference. |
Mandatory |
No response message body fields are specified by this international standard.
Table 45 describes the HTTP status codes that occur when updating a container object using CDMI content type.
HTTP Status |
Description |
204 No Content |
Operation successful, no data |
202 Accepted |
Container or a snapshot (sub-container object) is in the process of being created. The CDMI client should monitor 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 |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A 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. |
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.1
{ "metadata" : {
} , "exports" : { "OCCI/iSCSI" : { "identifier" : "0000706D0010B84FAD185C425D8B537E", "permissions" : "00007E7F00104EB781F900791C70106C" }, "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.1
{ "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.7 Delete a Container Object using CDMI Content Type
The following HTTP DELETE deletes an existing container object, all contained children, and snapshots at the specified URI.
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>.
The following capabilities describe 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.
The HTTP request header for deleting a CDMI container object using CDMI content type is shown in Table 46.
Header |
Type |
Description |
Requirement |
X-CDMI-Specification-Version |
Header String |
A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0" |
Mandatory |
No request message body fields are specified by this international standard.
No response headers are specified by this international standard.
No response message body fields are specified by this international standard.
Table 47 describes the HTTP status codes that occur when deleting a container object using CDMI content type.
HTTP Status |
Description |
204 No Content |
Container object was successfully deleted. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A resource was not found at the specified URI. |
409 Conflict |
The container object may not be deleted. |
EXAMPLE DELETE to the container object URI
DELETE /MyContainer/ HTTP/1.1 Host: cloud.example.com X-CDMI-Specification-Version: 1.0.1 |
:
The following shows the response.
HTTP/1.1 204 No Content |
9.8 Delete a Container Object using a Non-CDMI Content Type
The following HTTP DELETE deletes an existing container object, all contained children, and snapshots at the specified URI.
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>.
The following capabilities describe 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.
No request headers are specified by this international standard.
No request message body fields are specified by this international standard.
No response headers are specified by this international standard.
No response message body fields are specified by this international standard.
Table 48 describes the HTTP status codes that occur when deleting a container object using a non-CDMI content type.
HTTP Status |
Description |
204 No Content |
Container object was successfully deleted. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A resource was not found at the specified URI. |
409 Conflict |
The container object may not be deleted. |
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.9 Create (POST) a New Data Object using CDMI Content Type
The following HTTP POST creates a new data object as a child of the specified container object URI.
POST <root URI>/<ContainerName>/ 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.9.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 an object ID along with the 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.
• Future accesses to the URI created (or the object ID) shall succeed except when delays occur due to an 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 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.
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 "cdmi_serialize_dataobject_to_ID", "cdmi_serialize_container_to_ID", "cdmi_serialize_domain_to_ID", or "cdmi_serialize_queue_to_ID" system capabilities.
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.
The HTTP request headers for creating a new CDMI data object using CDMI content type are shown in Table 49.
Header |
Type |
Description |
Requirement |
Accept |
Header String |
"application/cdmi-object" |
Mandatory |
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.1, 1.5, 2.0" |
Mandatory |
The request message body fields for creating a new data object using CDMI content type are shown in Table 50.
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 • 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. • If creating an object by ID using /cdmi_objectid/, there is no parent container object, so the domain must be specified. |
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 pointed to by a reference. If other fields from this table are supplied when creating a reference, the server shall respond with a 400 Bad Request error response. |
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. |
|||
The HTTP response headers for creating a new CDMI data object using CDMI content type are shown in Table 51.
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.1". 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 |
The response message body fields for creating a new CDMI data object using CDMI content type are shown in Table 52.
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 shall not be returned. |
Mandatory |
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 shall not be returned. 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 • 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 shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object. |
Mandatory |
domainURI |
JSON String |
URI of the owning domain |
Mandatory |
capabilitiesURI |
JSON String |
URI to the capabilities for the object The capabilities URI returned is based on the object type and requested data system metadata fields. |
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 |
The value shall be an integer numeric 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 body metadata field, along with storage system metadata generated by the cloud storage system. See Clause 16 for a further description of metadata. |
Mandatory |
Table 53 describes the HTTP status codes that occur when creating a new data object using CDMI content type.
HTTP Status |
Description |
201 Created |
New data object was created. |
202 Accepted |
Data object is in the process of being created. The CDMI client should monitor completionStatus and percentComplete fields to determine the current status of the operation. |
400 Bad Request |
Invalid parameter in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A 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. |
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.1
{ "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.1 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.1
{ "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.1
{ "objectType": "application/cdmi-object", "objectID": "0000706D0010B84FAD185C425D8B537E", "domainURI": "/cdmi_domains/MyDomain/", "capabilitiesURI": "/cdmi_capabilities/dataobject/", "completionStatus": "Complete", "mimetype": "text/plain", "metadata": { "cdmi_acl": [ { "acetype": "CDMI_ACE_ACCESS_ALLOWED_TYPE", "identifier": "OWNER@", "aceflags": "CDMI_ACE_FLAGS_NONE", "acemask": "CDMI_ACE_ALL" } ] } } |
9.10 Create (POST) a New Data Object using a Non-CDMI Content Type
The following HTTP POST creates a new data object as a child of the specified container object URI.
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>.
The following capabilities describe 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.
The HTTP request header for creating a new CDMI data object using a non-CDMI content type is shown in Table 54.
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 |
The message body shall contain the contents (value) of the data object to be created.
The HTTP response header for creating a new CDMI data object using a non-CDMI content type is shown in Table 55.
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 |
No response message body fields are specified by this international standard.
Table 56 describes the HTTP status codes that occur when creating a new data object using a non-CDMI content type.
HTTP Status |
Description |
201 Created |
New data object was created. |
400 Bad Request |
Invalid parameter in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A resource was not found at the specified URI. |
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 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.11 Create (POST) a New Queue Object using CDMI Content Type
The following HTTP POST creates a new queue object as a child of the specified container object URI.
POST <root URI>/<ContainerName>/ 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.11.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 an object ID along with the 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.
• Future accesses to the URI created (or the object ID) shall succeed except when delays occur due to an 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 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.
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 data 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.
The HTTP request headers for creating a new CDMI queue object using CDMI content type are shown in Table 57.
Header |
Type |
Description |
Requirement |
Accept |
Header String |
"application/cdmi-queue" |
Mandatory |
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.1, 1.5, 2.0" |
Mandatory |
The request message body fields for creating a new queue object using CDMI content type are shown in Table 58.
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 • If different from the parent domain, the user must have the "cross_domain" privilege (see cdmi_member_privileges in Table 64). • If not specified, the parent domain will be used. • If creating an object by ID using /cdmi_objectid/, there is no parent container object, so the domain must be specified. |
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 to which a reference points. No other fields may be specified when creating a reference. |
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. |
|||
The response headers for creating a new CDMI queue object using CDMI content type are shown in Table 59.
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.1". 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 |
The response message body fields for creating a new CDMI queue object using CDMI content type are shown in Table 60.
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 shall not be returned. |
Mandatory |
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 shall not be returned. 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 • 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 shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object. |
Mandatory |
domainURI |
JSON String |
URI of the owning domain |
Mandatory |
capabilitiesURI |
JSON String |
URI to the capabilities for the object The capabilities URI returned is based on the object type and requested data system metadata fields. |
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 |
The value shall be an integer numeric 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 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 |
A range of values enqueued in the queue. The first value increases as items are deleted, and the second value increases as items are enqueued, e.g., • Create: -> "" , • Enqueue: -> "0-0", • Enqueue: -> "0-1", • Enqueue: -> "0-2", • Delete: -> "1-2", • Delete: -> "2-2", • Delete: -> "", and • Enqueue: -> "3-3". Clients should ensure that they use sufficient precision (e.g., 64-bits) when storing these values in an internal representation to avoid overflow. |
Mandatory |
Table 61 describes the HTTP status codes that occur when creating a new queue object using CDMI content type.
HTTP Status |
Description |
201 Created |
New queue object was created. |
202 Accepted |
Queue object is in the process of being created. The CDMI client should monitor completionStatus and percentComplete fields to determine the current status of the operation. |
400 Bad Request |
Invalid parameter or field names in the request |
401 Unauthorized |
Incorrect or missing authentication credentials |
403 Forbidden |
Client lacks the proper authorization to perform this request. |
404 Not Found |
A 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. |
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.1
{ } |
The following shows the response.
HTTP/1.1 201 Created Content-Type: application/cdmi-queue X-CDMI-Specification-Version: 1.0.1 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" : "" } |