Synopsis:
Creates a new container at the specified URI.
• <root URI> is the path to the CDMI cloud.
• <ContainerName> is zero or more intermediate containers that already exist. • <NewContainerName> is the name specified for the container to be created.
• Once created, the container can also be accessed at <root URI>/cdmi_objectid/<objectID>.
Delayed Completion of Create:
On a create operation for a container, the server may return a response of "202 Accepted". In this case, the container is in the process of being created. This response is particularly useful for long-running operations, for instance, for deserializing a source data object to create a large container hierarchy. Such a response has the following implications:
Metadata Name Description Source Permissions
cdmi_assignedsize The number of bytes that is reported via exported protocols (may be thin provisioned). This number may limit cdmi_size.
Client Read-Write
• The server returns an object identifier along with the "202 Accepted." With "202 Accepted", the server implies that the following checks have passed:
— User authorization for creating the container
— User authorization for read access to any source object for move, copy, serialize, or deserialize
— Availability of space to create the container or at least enough space to create a URI to report an error
• Future accesses to the URI created (or the object ID) will succeed modulo any delays due to use of eventual consistency.
• The client performs GET operations to the URI to track the progress of the operation. In particular, the server returns two fields in its response body to indicate progress:
— A mandatory completionStatus text field contains either "Processing", "Complete", or an error message
— An optional percentComplete field that indicates the percentage to which the last 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 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.
Capabilities:
The following capabilities describe the supported operations that can be performed when creating a new container:
• 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.
• If the new container object is a reference of an existing container object, support for the ability to create the reference is indicated by the presence of the "cdmi_create_reference" capability in the parent container.
• If the new container object is a copy of an existing container, support for the ability to copy is indicated by the presence of the "cdmi_create_copy" capability in the parent container.
• If the new container is the destination of a move, support for the ability to move the container is indicated by the presence of the "cdmi_create_move" capability in the parent container.
• If the new container is the destination of a deserialize operation, support for the ability to deserialize the source data object serialization of a container is indicated by the presence of the "cdmi_deserialize_container" capability in the parent container.
Request Headers:
Request Message Body:
Header Type Value Mandatory/Optional
Accept Header String "application/vnd.org.snia.cdmi.container+json" Mandatory Content-Type Header String "application/vnd.org.snia.cdmi.container+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- NoClobber
Header String
"true". Do not overwrite an existing container. If this header element is present and set to "true", it is an error for this operation to proceed. An update should be done instead.
Optional
Name Type Description Mandatory/Optional
metadata JSON
Object
Metadata for the container.
If this field is included when deserializing, copying, or moving a container, the value provided shall be replace the metadata from the source URI.
If this field is not specified, an empty JSON object ("{}") will be assigned as the field value.
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.
Optional
exports JSON
Object
A structure for each protocol enabled for this container. Optional
deserialize JSON
String
URI of a serialized CDMI data object that will be deserialized to create the new container, including all child objects inside the source serialized data object. When deserializing a container, any exported protocols from the original serialized container are not applied to the newly created container(s).
Optional*
copy JSON
String
URI of a CDMI container that will be copied into the new container, including all child objects under the source container. When copying a container, exported protocols are not preserved across the copy.
Optional*
move JSON
String
URI of a CDMI container that will be copied into the new container, including all child objects under the source container., then removing the container at the source URI upon the successful completion of the copy.
Optional*
reference JSON
String
URI of a CDMI data object that will be pointed to by a reference. No other fields may be specified when creating a reference.
*If present, only one of these parameters shall be specified in any given operation, and these fields are not persisted.
Response Headers:
Response Message Body:
Header Type Value Mandatory/Optional
Content-Type Header String "application/vnd.org.snia.cdmi.container+json" Mandatory X-CDMI- Specification- Version Header String
The server shall respond with the highest version supported by both the client and the server, for example, "1.0".
Mandatory
Name Type Description Mandatory/Optional
objectURI JSON
String
URI of the container as specified in the request.
Mandatory
objectID JSON
String
Object ID of the object Mandatory
parentURI JSON
String
URI for the parent 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 once 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 message.
Mandatory
percentComplete JSON String
The value shall be an integer numeric value from 0 through 100
Optional
metadata JSON
Object
Metadata for the container. 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 Chapter 16, “Metadata” for a further description of metadata.
Mandatory
exports JSON
Object
A structure for each protocol that is enabled for this container. See Chapter 13, “Exported Protocols”.
Optional (returned only if present)
snapshots JSON
Array
URI(s) of the SnapShot containers. See Chapter 14, “Snapshots”.
Optional (returned only if present)
Response Status:
Example Request:
PUT to the URI the container name and metadata
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. Child containers end with "/".
Mandatory
HTTP Status Description
201 Created New container was created
202 Accepted Container is in the process of being created. Investigate completionStatus and percentComplete parameters to determine the current status of the operation. 304 Not Modified The operation conflicts because the container already exists and the X-CDMI-
NoClobber header element was set to "true". 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. 409 Conflict The container name already exists.
PUT /MyContainer HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.container+json Content-Type: application/vnd.org.snia.cdmi.container+json X-CDMI-Specification-Version: 1.0 { "metadata" : { }, "exports" : { "OCCI/iSCSI" : { "identifier" : "AAAAFAAo7EFMb3JlbSBpcHN1bSBkb2xvciBzaXQgYW1ldCBhbWV0Lg==", "permissions" : "f63aaa26-30b7-4a30-91ca-1d03c1e52214" }, "Network/NFSv4" : { "identifier" : "/users", "permissions" : "domain" } } }
The response looks like: