10    Domain Object Resource Operations

10.1   Overview

Domain objects represent the concept of administrative ownership of stored data within a CDMI™ storage system. A CDMI offering may include a hierarchy of domains that provide access to domain-related information within a CDMI context. This domain hierarchy is a series of CDMI objects that correspond to parent and child domains, with each domain corresponding to logical groupings of objects that are to be managed together. Domain measurement information about objects that are associated with each domain flow up to parent domains, facilitating billing and management operations that are typical for a cloud storage environment.

A CDMI URI may optionally include domains using the following form:

http://example.com/cdmi_domains/parent_domain/child_domain/

Domain objects are created in the cdmi_domains container found in the root URI for the cloud storage system. If the cdmi_create_domain capability is present for the URI of a given domain, then the cloud storage system supports the ability to create child domains under the URI. If a cloud storage system supports domains, the cdmi_domains container shall be present.

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

10.1.1   Domain Object Metadata

The following domain-specific field shall be present for each domain (see Table 62).

Table 62 - Required Metadata for a Domain Object

Metadata Name

Type

Description

Requirement

cdmi_domain_enabled

JSON String

Indicates if the domain is enabled and specified at the time of creation. Values shall be "true" or "false".

   If a domain is disabled, the cloud storage system shall not permit any operations to be performed against any URI managed by that domain.

   If this metadata item is not present at the time of domain creation, the value is set to "false".

Mandatory

cdmi_domain_delete_reassign

JSON String

If the domain is deleted, indicates to which domain the objects that belong to the domain shall be reassigned. To delete a domain that contains objects, this metadata item shall be present. If this metadata item is not present or does not contain the URI of a valid domain that is different from the the URI of the domain being deleted, an attempt to delete a domain that has objects shall result in an HTTP status code of 409 Conflict.

Conditional

10.1.2   Domain Object Summaries

Domain object summaries provide summary measurement information about domain usage and billing. If supported, a domain summary container named "cdmi_domain_summary" shall be present under each domain container. Like any container, the domain summary subcontainer may have an Access Control List (ACL) (see 16.1) that restricts access to this information.

Within each domain summary container are a series of domain summary data objects that are generated by the cloud storage system. The "yearly", "monthly", and "daily" containers of these data objects contain domain summary data objects corresponding to each year, month, and day, respectively. These containers are organized into the following structures:

http://example.com/cdmi_domains/domain/

http://example.com/cdmi_domains/domain/cdmi_domain_summary/

http://example.com/cdmi_domains/domain/cdmi_domain_summary/cumulative

http://example.com/cdmi_domains/domain/cdmi_domain_summary/daily/

http://example.com/cdmi_domains/domain/cdmi_domain_summary/daily/2009-07-01

http://example.com/cdmi_domains/domain/cdmi_domain_summary/daily/2009-07-02

http://example.com/cdmi_domains/domain/cdmi_domain_summary/daily/2009-07-03

http://example.com/cdmi_domains/domain/cdmi_domain_summary/monthly/

http://example.com/cdmi_domains/domain/cdmi_domain_summary/monthly/2009-07

http://example.com/cdmi_domains/domain/cdmi_domain_summary/monthly/2009-08

http://example.com/cdmi_domains/domain/cdmi_domain_summary/monthly/2009-10

http://example.com/cdmi_domains/domain/cdmi_domain_summary/yearly/

http://example.com/cdmi_domains/domain/cdmi_domain_summary/yearly/2009

http://example.com/cdmi_domains/domain/cdmi_domain_summary/yearly/2010

The "cumulative" summary data object covers the entire time period, from the time the domain is created to the time it is accessed. Each data object at the daily, monthly, and yearly level contains domain summary information for the time period specified, bounded by domain creation time and access time.

If a time period extends earlier than the domain creation time, the summary information includes the time from when the domain was created until the end of the time period.

EXAMPLE 1   If a domain were created on July 4, 2009, at noon, the daily summary "2009-07-04" would contain information from noon until midnight, the monthly summary "2009-07" would contain information from noon on July 4 until midnight on July 31, and the yearly summary "2009" would contain information from noon on July 4 until midnight on December 31.

If a time period starts after the time when the domain was created and ends earlier than the time of access, the summary data object contains complete information for that time period.

EXAMPLE 2   If a domain were created on July 4, 2009, and on July 10, the "2009-07-06" daily summary data object was accessed, it would contain information for the complete day.

If a time period ends after the current access time, the domain summary data object contains partial information from the start of the time period (or the time the domain was created) until the time of access.

EXAMPLE 3   If a domain were created on July 4, 2009, and at noon on July 10, the "2009-07-10" daily summary data object was accessed, it would contain information from the beginning of the day until noon.

The information in Table 63 shall be present within the contents of each domain summary object, which is in JSON representation.

Table 63 - Contents of Domain Summary Objects

Metadata Name

Type

Description

Requirement

cdmi_domainURI

JSON String

Domain name corresponding to the domain that is summarized

Mandatory

cdmi_summary_start

JSON String

An ISO-8601 time indicating the start of the time range that the summary information is presenting

Mandatory

cdmi_summary_end

JSON String

An ISO-8601 time indicating the end of the time range that the summary information is presenting

Mandatory

cdmi_summary_objecthours

JSON String

The sum of the time each object belonging to the domain existed during the summary time period

Optional

cdmi_summary_objectsmin

JSON String

The minimum number of objects belonging to the domain during the summary time period

Optional

cdmi_summary_objectsmax

JSON String

The maximum number of objects belonging to the domain during the summary time period

Optional

cdmi_summary_objectsaverage

JSON String

The average number of objects belonging to the domain during the summary time period

Optional

cdmi_summary_puts

JSON String

The number of objects written to the domain

Optional

cdmi_summary_gets

JSON String

The number of objects read from the domain

Optional

cdmi_summary_bytehours

JSON String

The sum of the time each byte belonging to the domain existed during the summary time period

Optional

cdmi_summary_bytesmin

JSON String

The minimum number of bytes belonging to the domain during the summary time period

Optional

cdmi_summary_bytesmax

JSON String

The maximum number of bytes belonging to the domain during the summary time period

Optional

cdmi_summary_bytesaverage

JSON String

The average number of bytes belonging to the domain during the summary time period

Optional

cdmi_summary_writes

JSON String

The number of bytes written to the domain

Optional

cdmi_summary_reads

JSON String

The number of bytes read from the domain

Optional

cdmi_summary_charge

JSON String

An ISO 4217 currency code (see ISO 4217:2008) that is followed or preceded by a numeric value and separated by a space, where the numeric value represents the closing charge in the indicated currency for the use of the service associated with the domain over the summary time period

Optional

cdmi_summary_kwhours

JSON String

The sum of energy consumed (in kilowatt hours) by the domain during the summary time period

Optional

cdmi_summary_kwmin

JSON String

The minimum rate at which energy is consumed (in kilowatt hours per hour) by the domain during the summary time period

Optional

cdmi_summary_kwmax

JSON String

The maximum rate at which energy is consumed (in kilowatt hours per hour) by the domain during the summary time period

Optional

cdmi_summary_kwaverage

JSON String

The average rate at which energy is consumed (in kilowatt hours per hour) by the domain during the summary time period

Optional

An example of a daily domain summary object is as follows:

{

   "cdmi_domainURI" : "/cdmi_domains/MyDomain/",

   "cdmi_summary_start" : "2009-12-10T00:00:00",

   "cdmi_summary_end" : "2009-12-10T23:59:59",

   "cdmi_summary_objecthours" : "382239734",

   "cdmi_summary_puts" : "234234",

   "cdmi_summary_gets" : "489432",

   "cdmi_summary_bytehours" : "334895798347",

   "cdmi_summary_writes" : "7218368343",

   "cdmi_summary_reads" : "11283974933",

   "cdmi_summary_charge" : "4289.23 USD"

}

If the charge value is provided, the value is for the operational cost (excluding fixed fees) of service already performed and storage and bandwidth already consumed. Pricing of services is handled separately.

Domain summary information may be extended by vendors to include additional metadata or domain reports beyond the metadata items specified by this international standard, as long as the field names for those metadata items do not begin with "cdmi_".

10.1.3   Domain Object Membership

In cloud storage environments, in the same way that domains are often created programmatically, domain user membership and credential mapping also shall be populated using such interfaces. By providing access to user membership, this capability enables self-enrollment, automatic provisioning, and other advanced self-service capabilities, either directly using CDMI or through software systems that interface using CDMI.

The domain membership capability provides information about, and allows the specification of, end users and groups of users that are allowed to access the domain via CDMI and other access protocols. The concept of domain membership is not intended to replace or supplant ACLs (see 16.1), but rather to provide a single, unified place to map identities and credentials to principals used by ACLs within the context of a domain (see model described in 10.1.4). It also provides a place for authentication mappings to external authentication providers, such as LDAP and AD, to be specified.

If supported, a domain membership container named "cdmi_domain_members" shall be present under each domain. Like any container, the domain membership container such as an Access Control List (see 16.1) that restricts access to this information.

Within each domain membership container are a series of user objects that are specified through CDMI to define each user known to the domain. These objects are formatted into the following structure:

http://example.com/cdmi_domains/domain/

http://example.com/cdmi_domains/domain/cdmi_domain_members/

http://example.com/cdmi_domains/domain/cdmi_domain_members/john_doe

http://example.com/cdmi_domains/domain/cdmi_domain_members/john_smith

The domain membership container may also contain subcontainers with data objects. Data objects in these subcontainers are treated the same as data objects in the domain membership container, and no meaning is inferred from the subcontainer name. This is allowed to create different access security relationships for groups of user objects and to allow delegation to common set of members.

Table 64 lists the domain settings that shall be present within each domain member user object.

Table 64 - Required Settings for Domain Member User Objects

Metadata Name

Type

Description

Requirement

cdmi_member_enabled

JSON String

If true, this field indicates that requests associated with this domain member are allowed. If false, all requests performed by this domain member shall result in an HTTP status code of 403 Forbidden.

Mandatory

cdmi_member_type

JSON String

This field indicates the type of member record. Values include "user", "group", and "delegation".

Mandatory

cdmi_member_name

JSON String

This field contains the user or group name as presented by the client. This will normally be the standard full name of the principal.

Mandatory

cdmi_member_credentials

JSON String

This field contains credentials to be matched against the credentials as presented by the client. If this field is not present, one or more delegations shall be present and shall be used to resolve user credentials. As one cannot log in as a group, but only as a member of a group, "group" type member records shall not have credentials.

Optional

cdmi_member_principal

JSON String

This field indicates to which principal name (used in ACLs) the user or group is mapped. If this field is not present, one or more delegations shall be present and shall be used to resolve the principal.

Optional

cdmi_member_privileges

JSON Array of JSON Strings

This field contains a JSON list of special privileges associated with the user or "group".

The following privileges are defined:

   "administrator". All ACL access checks are always successful.

   "backup_operator". All read ACL access checks are always successful.

   "cross_domain". Operations specifying a domain other than the domain of the parent object are permitted. Unless this privilege is conferred by the user record or a group (possibly nested) to which the user or group belongs, all attempts to change the domain of objects to a domain other than the parent domain shall fail.

Mandatory

cdmi_member_groups

JSON Array of JSON Strings

This field contains a JSON array of group names to which the user or group belongs.

Optional

Table 65 lists the domain settings that shall be present within each domain member delegation object.

Table 65 - Required Settings for Domain Member Delegation Objects

Metadata Name

Type

Description

Requirement

cdmi_member_enabled

JSON String

If true, this field indicates that requests associated with this domain member are allowed. If false, all requests performed by this domain member shall result in an HTTP status code of 403 Forbidden.

Mandatory

cdmi_member_type

JSON String

This field indicates the type of member record. Values include "user" and "delegation".

Mandatory

cdmi_delegation_URI

JSON String

This field contains the URI of an external identity resolution provider (such as LDAP or Active Directory) or the URI of a Domain Membership Container.

External delegations are expressed in the form of ldap:// or ad://.

Mandatory

EXAMPLE 1   An example of a domain membership object for a user is as follows:

{

   "cdmi_member_enabled" : "true",

   "cdmi_member_type" : "user",

   "cdmi_member_name" : "John Doe",

   "cdmi_member_credentials" : "p+5/oX1cmExfOIrUxhX1lw==",

   "cdmi_member_groups" : [

        "users"

   ],

   "cdmi_member_principal" : "jdoe",

   "cdmi_privileges" : [

       "administrator",

       "cross_domain"

   ]

}

EXAMPLE 2   An example of a domain membership object for a delegation is as follows:

{

   "cdmi_member_enabled" : "true",

   "cdmi_member_type" : "delegation",

   "cdmi_delegation_URI" : "/cdmi_accounts/MyAccount/",

    

}

10.1.4   Domain Usage in Access Control

When a transaction is performed against a CDMI object, the associated domain object (i.e., the domain object indicated by the domainURI) specifies the authentication context. The user identity and credentials presented as part of the transaction are compared to the domain membership list to determine if the user is authorized within the domain and to resolve the user's principal. If resolved, the user’s principal is evaluated against the object's ACL to determine if the transaction is permitted.

When evaluating members within a domain, delegations are evaluated first, in any order, followed by user records, in any order. If there is at least one matching record and none of the matching records indicate that the user is disabled, the user is considered to be a member of the domain.

When a sub-domain is initially created, the membership container contains one member record that is a delegation in which the delegation URI is set to the URI of the parent domain.

10.1.5   Domain Object Representations

The representations in this clause are shown using JSON notation. Both clients and servers shall support UTF-8 JSON representation. The request and response message body JSON fields may be specified or returned in any order, with the exception that, if present, for domain objects, the childrenrange and children fields shall appear last and in that order.

10.2   Create a Domain Object using CDMI Content Type

10.2.1   Synopsis

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

PUT <root URI>/cdmi_domains/<DomainName>/<NewDomainName>/

Where:

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

   <DomainName> is zero or more intermediate domains that already exist.

   <NewDomainName> is the name specified for the domain to be created.

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

10.2.2   Capabilities

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

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

   If the new domain object is a copy of an existing domain object, support for the ability to copy is indicated by the presence of the cdmi_copy_domain capability in the source domain.

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

10.2.3   Request Headers

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

Table 66 - Request Headers - Create a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

Content-Type

Header String

"application/cdmi-domain"

Mandatory

X-CDMI-Specification-Version

Header String

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

Mandatory

10.2.4   Request Message Body

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

Table 67 - Request Message Body - Create a Domain Object using CDMI Content Type

Field Name

Type

Description

Requirement

metadata

JSON Object

Metadata for the domain object

   If this field is included when deserializing, serializing, copying, or moving a domain 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 domain object, the metadata from the source URI shall be used.

   If this field is included when creating a new domain 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 domain object by specifying a value, an empty JSON object ("{}")(i.e., "{}") shall be assigned as the field value.

Optional

copy

JSON String

URI of a CDMI domain that shall be copied into the new domain, including all child domains and membership from the source domain

Optionala

move

JSON String

URI of an existing local CDMI domain object (source URI) that shall be relocated, along with all child domains, to the URI specified in the PUT. The contents of the domain and all sub-domains, including the object ID, shall be preserved by a move, and the domain and sub-domains 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 error code, and the source and destination are left unchanged.

Optionala

deserialize

JSON String

URI of a serialized CDMI data object that shall be deserialized to create the new domain, including all child objects inside the source serialized data object

Optionala

deserializevalue

JSON String

A domain 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.

10.2.5   Response Headers

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

Table 68 - Response Headers - Create a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-domain"

Mandatory

X-CDMI-Specification-Version

Header String

The server shall respond with the highest version supported by both the client and the server, e.g., "1.0.2".

If the server does not support any of the versions supported by the client, the server shall return a 400 Bad Request status code.

Mandatory

10.2.6   Response Message Body

The response message body fields for creating a domain object using CDMI content type is shown in Table 69.

Table 69 - Response Message Body - Create a Domain Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-domain"

Mandatory

objectID

JSON String

Object ID of the domain

Mandatory

objectName

JSON String

Name of the object

Mandatory

parentURI

JSON String

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

Mandatory

parentID

JSON String

Object ID of the parent container object

Mandatory

domainURI

JSON String

URI of the owning domain. A domain object is always owned by itself.

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

metadata

JSON Object

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

Mandatory

childrenrange

JSON String

The sub-domains of the domain expressed as a range. If a range of sub-domains is requested, this field indicates the children returned as a range.

Mandatory

children

JSON Array

Names of the children domains in the domain. Child containers end with "/".

Mandatory

10.2.7   Response Status

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

Table 70 - HTTP Status Codes - Create a Domain Object using CDMI Content Type

HTTP Status

Description

201 Created

The new domain object was created.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The resource was not found at the specified URI.

409 Conflict

The domain name already exists.

10.2.8   Example

EXAMPLE   PUT to the domain URI the domain name and metadata:

PUT /cdmi_domains/MyDomain/ HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-domain

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

        

   }

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID" : "00007E7F00104BE66AB53A9572F9F51E",

   "objectName" : "MyDomain/",

   "parentURI" : "/cdmi_domains/",

    "parentID" : "00007E7F0010C058374D08B0AC7B3550",

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

   "capabilitiesURI" : "/cdmi_capabilities/domain/",

   "metadata" : {

        

   },

   "childrenrange" : "0-1",

   "children" : [

       "cdmi_domain_summary/",

       "cdmi_domain_members/"

    ]

}

10.3   Read a Domain Object using CDMI Content Type

10.3.1   Synopsis

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

GET <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/

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

GET <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/?<fieldname>;<fieldname>;...

GET <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/?children:<range>;...

GET <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/?metadata:<prefix>;...

Where:

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

   <DomainName> is zero or more parent domains.

   <TheDomainName> is the name specified for the domain 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 object shall also be accessible at <root URI>/cdmi_objectid/<objectID>/.

10.3.2   Capabilities

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

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

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

10.3.3   Request Headers

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

Table 71 - Request Headers - Read a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

Accept

Header String

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

Optional

X-CDMI-Specification-Version

Header String

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

Mandatory

10.3.4   Request Message Body

A request message body shall not be provided.

10.3.5   Response Headers

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

Table 72 - Response Headers - Read a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

X-CDMI-Specification-Version

Header String

The server shall respond with the highest version supported by both the client and the server, e.g., "1.0.2".

If the server does not support any of the versions supported by the client, the server shall return a 400 Bad Request status code.

Mandatory

Content-Type

Header String

"application/cdmi-domain"

Mandatory

Location

Header String

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

Conditional

10.3.6   Response Message Body

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

Table 73 - Response Message Body - Read a Domain Object using CDMI Content Type

Field Name

Type

Description

Requirement

objectType

JSON String

"application/cdmi-domain"

Mandatory

objectID

JSON String

Object ID of the domain

Mandatory

objectName

JSON String

Name of the object

Mandatory

parentURI

JSON String

URI for the parent object

Mandatory

parentID

JSON String

Object ID of the parent container object

Mandatory

domainURI

JSON String

URI of the owning domain. A domain object is always owned by itself.

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

Mandatory

metadata

JSON Object

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

Mandatory

childrenrange

JSON String

The sub-domains of the domain expressed as a range. If a range of sub-domains is requested, this field indicates the children returned as a range.

Mandatory

children

JSON Array

The children of the domain. Sub-domains end with "/".

Mandatory

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.

10.3.7   Response Status

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

Table 74 - HTTP Status Codes - Read a Domain Object using CDMI Content Type

HTTP Status

Description

200 OK

The domain object content was returned in the reponse.

302 Found

The URI is a reference to another URI.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The resource was not found at the specified URI.

406 Not Acceptable

The server is unable to provide the object in the content type specified in the Accept header.

10.3.8   Examples

EXAMPLE 1   GET to the domain URI to read all the fields of the domain:

GET /cdmi_domains/MyDomain/ HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

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

   "objectID" : "00007E7F00104BE66AB53A9572F9F51E",

   "objectName" : "MyDomain/",

   "parentURI" : "/cdmi_domains/",

    "parentID" : "00007E7F0010C058374D08B0AC7B3550",

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

   "capabilitiesURI" : "/cdmi_capabilities/domain/",

   "metadata" : {

        

   },

   "childrenrange" : "0-1",

   "children" : [

       "cdmi_domain_summary/",

        "cdmi_domain_members/"

   ]

}

EXAMPLE 2   GET to the domain URI to read all the parentURI and children of the domain:

GET /MyDomain/?parentURI;children HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

   "parentURI" : "/cdmi_domains/",

   "children" : [

       "cdmi_domain_summary/",

        "cdmi_domain_members/"

   ]

}

EXAMPLE 3   GET to the domain URI to read the first two children of the domain:

GET /MyDomain/?childrenrange;children:0-1 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

   "childrenrange" : "0-1",

   "children" : [

       "cdmi_domain_summary/",

        "cdmi_domain_members/"

   ]

}

10.4   Update a Domain Object using CDMI Content Type

10.4.1   Synopsis

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

PUT <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/

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

PUT <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/?metadata:<metadataname>;...

Where:

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

   <DomainName> is zero or more parent domains.

   <TheDomainName> is the name specified for the domain to be updated.

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

10.4.2   Capability

The following capability describes the supported operations that may be performed when updating an existing domain:

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

10.4.3   Request Headers

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

Table 75 - Request Headers - Update a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-domain"

Mandatory

X-CDMI-Specification-Version

Header String

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

Mandatory

10.4.4   Request Message Body

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

Table 76 - Request Message Body - Update a Domain Object using CDMI Content Type

Field Name

Type

Description

Requirement

metadata

JSON Object

Metadata for the domain 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

copy

JSON String

URI of a CDMI domain object that shall be copied into the existing domain object. Only the metadata and membership of the domain shall be copied, not any sub-domains of the domain.

Optionala

deserialize

JSON String

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

If the serialized domain does not contain children, the update is applied only to the domain object, and any existing children are left as-is. If the serialized domain 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

deserializevalue

JSON String

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

If the serialized domain does not contain children, the update is applied only to the domain object, and any existing children are left as-is. If the serialized domain 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

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

10.4.5   Response Header

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

Table 77 - Response Header - Update a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

Location

Header String

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

Conditional

10.4.6   Response Message Body

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

10.4.7   Response Status

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

Table 78 - HTTP Status Codes - Update a Domain Object using CDMI Content Type

HTTP Status

Description

204 No Content

The operation was successful; no data was returned.

302 Found

The URI is a reference to another URI.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The resource was not found at the specified URI.

409 Conflict

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

10.4.8   Example

EXAMPLE   PUT to the domain URI to set new field values:

PUT /cdmi_domains/myDomain/ HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-domain

X-CDMI-Specification-Version: 1.0.2

 

{

   "metadata" : {

        "test" : "value"

   }

}

The following shows the response.

HTTP/1.1 204 No Content

10.5   Delete a Domain Object using CDMI Content Type

10.5.1   Synopsis

To delete an existing domain object and transfer all objects associated with that domain to another domain (to preserve access), the following request shall be performed:

DELETE <root URI>/cdmi_domains/<DomainName>/<TheDomainName>/

Where:

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

   <DomainName> is zero or more parent domains.

   <TheDomainName> is the name specified for the domain to be deleted.

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

10.5.2   Capability

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

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

10.5.3   Request Headers

The HTTP request headers for deleting a CDMI domain object using CDMI content type are shown in Table 79.

Table 79 - Request Headers - Delete a Domain Object using CDMI Content Type

Header

Type

Description

Requirement

X-CDMI-Specification-Version

Header String

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

Mandatory

10.5.4   Request Message Body

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

10.5.5   Response Headers

Response headers may be provided as per RFC 2616.

10.5.6   Response Message Body

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

10.5.7   Response Status

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

Table 80 - HTTP Status Codes - Delete a Domain Object using CDMI Content Type

HTTP Status

Description

204 No Content

The domain was successfully deleted.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The resource was not found at the specified URI.

409 Conflict

The domain cannot be deleted because there are objects belonging to the domain, and cdmi_domain_delete_reassign is missing, invalid, or unusable.

10.5.8   Example

EXAMPLE   DELETE to the domain URI:

DELETE /cdmi_domains/MyDomain/ HTTP/1.1

Host: cloud.example.com

X-CDMI-Specification-Version: 1.0.2

The following shows the response.

HTTP/1.1 204 No Content