4    Conventions

4.1   Interface Format

Each interface description has nine components, as described in Table 1.

Table 1 - Interface Format

Component

Description

Synopsis

The GET, PUT, POST, and DELETE semantics

Delayed Completion of Create

For long-running operations, a description of behavior when the operation does not immediately complete

Capabilities

A description of the supported operations

Request Headers

The request headers, such as Accept, Authorization, Content-Length, Content-Type, X-CDMI-Specification-Version

Request Message Body

A description of the message body contents

Response Headers

The response headers, such as Content-Length, Content-Type

Response Message Body

A description of the message body contents

Response Status

A list of HTTP status codes

Example

An example of the operation

4.2   Typographical Conventions

All code text is shown in a fixed-width font, as follows:

EXAMPLE    

PUT /MyContainer/MyDataObject.txt HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-object

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "mimetype" : "text/plain",

   "metadata" : {

        

   },

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

}

4.3   Request and Response Body Requirements

In request and response message body tables, the Requirement column contains one of the following three values:

   Mandatory. The value specified in this row shall be provided.

   Conditional. If the condition(s) specified in the "Description" cell of this row (to the left of the Requirement) is met, the value specified in this row shall be provided. Otherwise it may be provided unless the Description specifically prohibits it, in which case it shall not be provided.

   Optional. The value specified in this row may be provided.

4.4   Key Word Requirements

In this international standard, the key words in Table 2 shall be interpreted as described in RFC 2119.

Table 2 - Key Word Requirements

Key Words

Description

shall
must
required

An action described with any of these key words is unconditionally required.

shall not
must not

An action described with either of these key word phrases is unconditionally prohibited.

should
recommended

Valid reasons may exist in specific circumstances to ignore a particular action described with either of these key words, but the full implications must be understood and carefully weighed before choosing a different course.

should not
not recommended

Valid reasons may exist in specific circumstances to accept a particular action described by either of these key word phrases, but the full implications should be understood and the case carefully weighed before implementing any action described with these key words.

may
optional

An action described with either of these key words is truly optional. One vendor may choose to include the option because a particular marketplace requires it or because the vendor feels that it enhances the product, while another vendor may omit the same option. An implementation which does not include a particular option must be prepared to interoperate with another implementation that does include the option, though perhaps with reduced functionality. Likewise, an implementation which does include a particular option must be prepared to interoperate with another implementation that does not include the option (except, of course, for the feature the option provides).