NOTE-ice-20000322

 

Editors:

Jay Brodsky, Tribune Media Services

Bruce Hunt, Adobe Systems, Inc.

Sami Khoury, What U Want, Inc.

Laird Popkin, Sotheby's Holdings
 

ICE Authoring Group:

Michael Branch, Vignette Corporation

Jay Brodsky, Tribune Media Services

Phil Gibson, National Semiconductor Corporation

Jack Gudenkauf, Microsoft Corporation

Martin Hardee, Sun Microsystems, Inc.

Bruce Hunt, Vice-Chairman, ICE-AG, Adobe Systems, Inc.

Brad Husick, (Invited Expert)Vignette Corporation

Kimberly Jones, CNET: The Computer Network

Dianne Kennedy, (Invited Expert), XMLXperts & IDEAlliance

Sami Khoury, What U Want, Inc.

Daniel Koger, BEST Consulting

Erik Leckner, Seagate Technology, Inc.

Richard Martin, Active Data Exchange, Inc.

Laird Popkin, Chairman ICE-AG, Sotheby's Holdings

Nathan Pride, Wavo Corporation

Adam Souzis, Kinecta Corporation

Status of this Document

This document is a draft prepared for XML Europe by the ICE Authoring Group

ICE 1.1 is an ICE 1.0 compatible update to the ICE 1.0 specification.  This update is made in response to the implementation experience that has been gained over the past year.  It differs from the ICE 1.0 specification in that it corrects several minor deficiencies in the original specification.  It corrects several typographic errors.  It continues the clarification of the specification  to assist  developers in achieving inter-operable implementations.  Finally, ICE 1.1 specifies several of the most asked for implementation features.   ICE 1.1 is fully upwards compatible with ICE 1.0 in that an ICE 1.0 implementation can inter-operate with an ICE 1.1 implementation using any function of ICE 1.0.  ICE 1.1 implementations add capabilities ( most notably extensibility ) that are only accessible to other ICE 1.1 implementations.

The ICE authoring group and IDEAlliance recommend that implementations be updated to conform to the ICE 1.1 specification. The minor changes and added function greatly enhance the usability of the protocol in a very wide range of syndication applications and can provide a substantial foundation for delivering syndication solutions.

Abstract

Table of Contents

1. Introduction
   1. ICE Design Goals
   2. How ICE relates to other standards
      1. XML
      2. CDF
      3. OSD
      4. P3P
      5. WebDAV
      6. HTTP DRP
      7. SMIL
   3. Definitions
      1. Requirement Wording Note
      2. ICE Semantic Definitions
   4. Technical Decisions
      1. ICE Constraints and XML-Schema
      2. Defining ICE using a DTD and XML-Data
      3. Use of HTTP POST transport mechanism
      4. Security
   5. Internationalization Issues
   6. Structure of this Document
2. ICE Overview
   1. Simple ICE Scenarios
      1. Headline Scenario
      2. Parts Scenario
   2. Protocol Overview
      1. Payloads, Requests, and Responses
      2. Request/Response model
      3. Subscriber/Syndicator, Requester/Responder, Sender/Receiver
      4. Minimal Subscriber Implementation and Unsolicited Message
   3. Binding of ICE to HTTP
      1. Use of HTTP POST
      2. Mapping the ICE Request/Response Model to HTTP POST/Response
      3. Multiple Requests in a Single Payload
      4. Content Type in HTTP Header
3. Protocol Infrastructure
   1. Syntax and Format
      1. XML Syntax
      2. Generic Rules for Attribute Formats
   2. Identifiers
      1. Subscriber and Syndicator Identifiers
      2. Other Identifiers
   3. Dates and Times
      1. ICE Date Format
      2. ICE Time Format
      3. Sub second Resolution
      4. Time Zones
      5. ICE Date and Time Format
      6. ICE Duration Format
   4. Status and Error code formats
      1. No HTTP Relationship
      2. Status Code Format
      3. Body
      4. Defined Status Codes
      5. Redirection
   5. ICE Payload Detail
      1. Payload XML Declarations
      2. Payload Element Definition
   6. Payload Header Fields
      1. ice-sender
      2. ice-receiver
      3. ice-user-agent
   7. ICE Requests and ICE Responses
      1. ice-request
      2. ice-response
      3. Responses containing errors and additional data
   8. Surprise ice-code Messages, and Package Confirmation
      1. Format of ice-code message
      2. Semantics of Package Confirmation
      3. Specific Confirmation Codes
   9. Example NOP Message
      1. A Single NOP
      2. Multiple NOPs
   10. Unsolicited Message Operation
       1. General Unsolicited Model
       2. Format of unsolicited-now
       3. Format of unsolicited-request
       4. Format of unsolicited-response
       5. Asymmetry and Implementation Requirements
       6. Policy decisions
       7. Example exchanges
4. Catalogs and Subscription Establishment
   1. Subscription Establishment Overview
   2. Delivery Policies
      1. ice-delivery-policy
      2. ice-delivery-rule
      3. Negotiation information
   3. Catalogs
      1. Catalog Format
      2. Offer Group and Offer Formats
      3. Business Terms
      4. Protocol Operation: Get Catalog
   4. Subscribing and Negotiation Model
      1. Negotiation Model
      2. Basic Negotiation Flow: Offer / Sorry / OK
      3. Protocol operation
      4. Trivial Negotiation Implementation
      5. Non-trivial Negotiation Implementation
      6. Negotiation Process
         1. Overview
         2. Single Parameter Resolution
         3. Multiple Parameter Resolution
         4. Convergence
   5. Parameter Negotiation Elements
      1. Ice-negotiable Content
      2. Ice-range
      3. Ice-span
      4. Ice-enum
      5. Subscription Operating Parameters
         1. Month Day
         2. Week Day
         3. Start Date
         4. Stop Date
         5. Start Time
         6. Duration
         7. Minimum Update Interval
         8. Maximum Update Interval
         9. Minimum Number of Updates
         10. Maximum Number of Updates
         11. Push or Pull mode
      6. Negotiation Examples
         1. Multiple Video Stream Syndication
         2. ICE Delivery Rule Negotiation
   6. Status Operations
      1. ice-cancel
      2. ice-change-subscription
      3. ice-get-status
5. Packages and Delivery
   1. Sequenced Package Model
      1. Discrete Package Model
      2. Strictly Ordered Package Model
      3. Package Sequence Identifier
      4. Packages and Package Sequence Identifiers
      5. Sequenced Package Example
      6. Example Pseudo protocol Exchange
   2. Package containment model
      1. Package format
      2. Add operations
         1. ice-item
         2. ice-item-ref
         3. ice-item-group
      3. Remove operation
      4. Extensibility
   3. Package Pull Operations
   4. Package Push Operations
   5. Miscellaneous Package Operations
      1. Awaiting Confirmations
      2. Obtaining Package Sequence Information
      3. Individual Asset Repair
6. Event Logs
   1. ICE defines generic transport for multiple log file formats
   2. Event log operations
   3. ICE event log format
   4. Issues and Discussion
7. Miscellaneous Protocol Operations
   1. No Operation
   2. Notify: Text Messages
8. Extending ICE
   1. Introduction
   2. Content Model Extensions
      1. Elements permitting extension
      2. Required extension Semantics
      3. Alternative Log Format
      4. Extending ice-items content
      5. Domain specific package content
   3. Subscription Extensions
   4. Protocol Extensions
      1. Example Protocol Extension - Down-time Messages

1. Appendix: Complete ICE DTD
2. Appendix: ICE Revisions
3. Appendix: Change Log

• References

1. Introduction

• Before successfully sharing and reusing information, both ends need a common vocabulary.
• Before successfully transferring any data and managing the relationship, both ends need a common protocol and management model.

ICE completes the picture by providing the solution for the other half of the puzzle. Specifically, ICE manages and automates establishment of syndication relationships, data transfer, and results analysis. When combined with an industry specific vocabulary, ICE provides a complete solution for syndicating any type of information between information providers and their subscribers.

1.1 ICE Design Goals

1. ICE shall be straightforwardly usable over the Internet.
2. ICE shall support a wide variety of applications and not constrain data formats.
3. ICE shall conform to a specific XML syntax.
4. The ICE requirements shall constrain the ICE process to practical and implementable mechanisms.
5. ICE shall be open for future, unknown uses.
6. Compactness of representation in ICE is of minimal importance. Note: this is a statement about low level encoding methodology, e.g., the use of XML in general and the particular choice of tag and attribute names in particular.
7. ICE shall keep protocol and packaging overhead to a minimum. Note: this is a statement about protocol overhead in the sense of round trips, complexity, and other high level performance effects. It is not a contradiction of the previous point. The design of ICE achieves its performance objectives by optimizing the high level design of the protocol flow and state management, not by micro optimizing the spelling of individual packets.

1.2 How ICE relates to other standards

1.2.1 XML

1.2.2 CDF

We expect ICE will be useful for server to server syndication to distribute and/or aggregate content to/from various push servers, whereas CDF is useful for server to browser applications.

1.2.3 OSD

We expect ICE to be useful for server to server syndication to distribute and/or aggregate content to/from one OSD server to another, whereas OSD continues to be useful for its intended domain of distributing and installing software directly to target desktop and work group server machines.

1.2.4 P3P

1.2.5 WebDAV

WebDAV addresses a collaborative authoring environment and has very little overlap with ICE.

1.2.6 HTTP DRP

DRP focuses on the differential update of information organized as a hierarchy of files. As such, it could be used to solve a portion of the data transfer problems addressed by ICE, but only for those content syndication situations that are file centric. ICE solves a more general problem of asset exchange, where assets may not necessarily be files in a hierarchy. ICE also addresses explicit subscription relationship management, asset management, reliable sequenced package delivery, asset repair operations, constraints, etc. whereas DRP addresses none of those.

1.2.7 SMIL

SMIL (the Synchronized Multimedia Interchange Language) is an appropriate container format to be carried in an ICE package.  SMIL defines the temporal, layout and linking relationship between media components of a presentation and therefore has the potential to be an important content manager format for syndicated media.  ICE optimally carries content described by XML documents. SMIL is a standardized means for managing dynamic content based on an XML document.  There is a natural complementary affinity between ICE and SMIL.

1.3 Definitions

1.3.1  Requirement Wording Note

In the HTML version of this specification, those key words are CAPITALIZED BOLD. Capitalization is significant; uncapitalized uses of the key words are intended to be interpreted in their normal, informal, English language way. Bold face is not significant, and is used to aid comprehension, but the bold font is non normative and the absence of a bold font MUST NOT be given any semantic interpretation.

1.3.2 ICE Semantic Definitions

catalog

A set of subscription offers. A Subscriber obtains a catalog from a Syndicator, and uses the offers within the catalog to initiate the ICE subscription protocol.

collection

The result of a Subscriber processing all package deliveries in a single subscription, that is, the current content of a subscription. This is equivalent to the set of all items that a Syndicator would deliver in a full update of a subscription. This is not necessarily every item a Syndicator would transmit over time in a given subscription, because of incremental update.

ICE

Information and Content Exchange.

item

A single delivery instance of an arbitrary data type. For example, if a database record were being distributed, each field might be encapsulated as an item. Or, if a prospectus consisting of an HTML file and two GIF image files is being distributed, each of the files would be an item.

ICE/HTTP

The specific binding of the ICE protocol to the HTTP protocol.

message

The abstract concept of an atomic unit of communication. In this specification, the term message does not denote any specific protocol structure; rather, it is used to denote an abstract communication concept.

Minimal Subscriber

A Subscriber ICE implementation that has no persistent server component and therefore cannot receive syndicator initiated request messages.

negotiation

The Subscriber and Syndicator may negotiate to arrive at mutually agreeable delivery methods and schedules.

For example, both sides may have a preferred set of delivery times.  The ICE negotiation model is not an attempt to automate the arcane and baroque nature of human to human business deal negotiation.

package

A single delivery instance of a group of items. For example, a single issue of a parts manual or a single set of headlines. A package is the atomic unit of information distribution in ICE.

package sequence

An ordered series of packages delivered over time.

payload

A protocol structure encapsulating a set of logical ICE operations delivered at discrete intervals. A payload is a single instance of an XML document formatted according to the protocol definitions contained in this specification.

Receiver

Generic term referring to the target of an ICE payload. The term Receiver is used when it is possible for either the Subscriber or the Syndicator to be the party receiving the payload.

Request

A message asking for the performance of an operation. Requests in ICE are messages carried by payloads.

Requester

Generic term referring to the initiator of an ICE payload request.

Responder

Generic term referring to the recipient of an ICE payload request.

Response

A message containing the results of an operation. Responses in ICE are messages carried by payloads.

Sender

Generic term referring to the originator of an ICE payload. The term Sender is used when it is possible for either the Subscriber or the Syndicator to be the party sending the payload.

Subscriber

One of the two parties in an ICE relationship (the other one being the Syndicator). The Subscriber uses ICE to obtain information and content from the Syndicator.

subscription

An agreement to deliver a package sequence from a Syndicator to a Subscriber. There may be many independent subscriptions between a Syndicator and a Subscriber.

subscription element

A persistent identifier of all versions of an item or item group in a subscription. The subscription element may have many versions over time, and thus may have been represented by different items. For example, a company logo is a single subscription element, that can be updated over time. Every subscription element has a unique subscription element ID assigned by the syndicator.

subscription offer

A proposed set of parameters for a particular subscription. Within ICE, the term subscription offer has a precise meaning directly related to the corresponding protocol data structure; do not confuse the usage of the term "offer" in this specification with the more generic and abstract concept of offers in the business world sense.

Syndicator

One of the two parties in an ICE relationship (the other one being the Subscriber). The Syndicator uses ICE to send information and content to the Subscriber.

unsolicited message

A protocol mechanism used in ICE to provide a way for a Syndicator to initiate communication to a Minimal Subscriber.

1.4 Technical Decisions

1.4.1 ICE Constraints and XML-Schema

The ICE Authoring Group felt strongly that:

• Constraints were a necessary part of a syndication solution.
• No existing languages, or nascent standards efforts, provided a solution.
• No clear winners were evident among the variety of potential future standards in this area.

• ICE provides a mechanism to reference constraints in a subscription
• ICE provides a mechanism for describing (by simple name) the type of constraints mechanism being referenced.
• ICE provides specific error and status codes for handling constraint violation errors.

The Authoring Group intends to go one step further and define an interim constraint language, tentatively named ICE Constraints. The ICE Constraints language will suffice to meet the basic requirements of content Syndicators and their subscribers, while allowing time for general and more complete solutions to develop. We expect the ICE Constraints language will also be a useful source of requirements for future general purpose constraint language designers.

Note that a conforming ICE implementation need not implement any constraint processing at all; like DTD validation and a number of other ICE features, constraint processing is entirely a quality of implementation issue. Its presence or absence has no effect whatsoever on the interoperability of two ICE implementations, because nothing in the protocol state machine flow depends on constraint processing.

1.4.2 Defining ICE using a DTD and XML-Schema

Inherently, because ICE is built using well formed XML documents, many different methods could have been used to specify syntax. For example, BNF can be used to define the protocol format as a grammar, complete with '<' and '/>' as literal elements in the productions. The authors of CDF in fact did this (albeit probably for historical reasons).

The use of a DTD mechanism implies very little about interoperability among implementations and about the ability to use other mechanisms in the future. The important question to ask is: what is the format of the pattern of bits exchanged over the wire. Whether specified using a DTD, XML-Data, BNF, a lex/yacc grammar, or lisp program, the "instance" (pattern of bits in the ICE document) is the same. This is the important point.

There are two places where a DTD is implied. One is in the following requirements:

• A Receiver MAY perform validation on incoming ICE payloads.
• A Sender MUST send only valid ICE payloads.

The second place where a DTD is implied is in the DOCTYPE declaration of an ICE packet. A Receiver MAY simply ignore this declaration if the Receiver is not using a DTD. A Sender MUST supply this declaration, but this presents no particular burden to Sender implementations that function without DTDs; they can simply point to a publicly available known ICE DTD for the purposes of meeting this requirement.

1.4.3 Use of HTTP POST transport mechanism

This specification explicitly discusses the binding of the generic ICE protocol to the HTTP transport mechanism. This specification uses the term ICE/HTTP where necessary to specifically refer to the concept of ICE bound to an HTTP transport mechanism.

To preserve the goal of being transport independent, and also to enable ICE to operate within existing network infrastructures, ICE/HTTP transmits payloads using the HTTP POST/Response mechanism. ICE/HTTP does not define any new HTTP headers or modify the HTTP protocol in any way; rather, the entire ICE request/response exchange is contained in the body of the HTTP POST and its associated HTTP Response.

1.4.4 Security

In the specific case of digital signatures, non repudiation, and similar concepts, two things have happened that have steered the Authoring Group away from the notion of having digital signatures inside ICE itself:

• Separate efforts are underway to define digital signing standards for XML documents. The ICE Authoring Group felt that duplicating such work within ICE was not warranted.
• Defining digital signing standards for XML documents is quite tricky, and requires defining a canonical text representation of the documents (because the digital hash functions hash the textual representation of a document, not its logical representation). The ICE Authoring Group did not want to define their own, possibly conflicting, canonical representation rules to solve this problem.

• Encryption can be accomplished at the transport level, e.g., via SSL, PGP, or S/MIME.
• Applications can agree to send digitally signed content as items within the ICE protocol, with verification performed at the application level (above ICE).
• Syndicators and subscribers can be authenticated using certificates implemented at the transport level.
• Syndicators can offer extended ICE subscriptions where the specific content structures to be encrypted as well as the encryption types may be negotiated using subscription extension described in section 8.3.

1.5 Internationalization Issues

1. Support for International Character Sets. ICE itself defines no specific mechanisms for encoding or identifying character sets. Instead, ICE relies on capabilities in XML for encoding and supporting international character sets.
2. Protocol Error Message Text. The error messages in an ice-code (see 3.4) include both a numeric error code and a short phrase, such as "OK" or "Not found". As is described in detail in 3.4.4, the phrase is intended for informational purposes only; it is the numeric error code itself that defines the semantics of the error message. Internationalized implementations of ICE are expected to convert the numeric ICE error code into an appropriate presentation string in the local language. Thus, there is no requirement for ICE to support multi-lingual versions of the error code phrase, such as "Mahalo" instead of "OK" in the 200 code.
3. Other Protocol Text Strings. The ICE protocol sometimes uses string values as semantic identifiers. For example, an ice-sender (see 3.6.1) encodes the senders role as either "subscriber" or "syndicator". These textual strings are intended as arbitrary tokens representing a specific concept; they are not intended for presentation and thus have no impact on internationalization issues.
4. Language identifier for textual data. Some ICE elements and attributes are specifically designed for the transport of textual data intended for use by humans. For example, the ice-business-term element (see 4.3.1). ICE provides a xml:lang attribute in all places where human readable text is being transported and might require an identification of its specific language encoding. When used, the xml:lang attribute MUST be filled in according to standards RFC-1766 (Tags for the Identification of Languages) and ISO-639 (Code for the representation of names of languages) as is required by the XML Specification.

1.6 Structure of this Document

• Chapter 2 introduces basic ICE protocol concepts, without regard to the specifics of the format.
• Chapter 3 describes the fundamental ICE formats and foundation protocol elements
• Chapter 4 describes subscription management
• Chapter 5 describes the ICE packages, the Sequenced Package Model for incremental and full updates, and associated management operations.
• Chapter 6 describes the ICE event log operations
• Chapter 7 describes miscellaneous ICE operations
• Chapter 8 describes how to extend the ICE protocol

2. ICE Overview

The Subscriber receives the information regarding their account (their subscriber identification and location to request their catalog) and how to obtain a catalog of subscription offers. At this point actual ICE operation can begin. The important point to understand is that ICE starts after the two parties have already agreed to have a relationship, and have already worked out the contractual, monetary, and business implications of that relationship.

The ICE protocol covers four general types of operations:

• Subscription Establishment and Management
• Data Delivery
• Event logs
• Miscellaneous

The relationship then moves on to the steady state, where the primary message exchanges center on data delivery. ICE uses a package concept as a container mechanism for generic data items. ICE defines a sequenced package model allowing syndicators to support both incremental and full update models. ICE also defines push and pull data transfer models.

Managing exceptional conditions and being able to diagnose problems is an important part of syndication management; accordingly, ICE defines a mechanism by which event logs can be automatically exchanged between (consenting) Subscribers and Syndicators.

Finally, ICE provides a number of mechanisms for supporting miscellaneous operations, such as the ability to renegotiate protocol parameters in an established relationship, the ability to send unsolicited ad-hoc notifications (i.e., textual messages) between systems (presumably ultimately targeted at administrators), the ability to query and ascertain the state of the relationship, etc.

2.1 Simple ICE Scenarios

2.1.1 Headline Scenario

Subscribers who sign up for the headline service can collect these headlines and use them on their own site. They display the headlines on their own site, with the URL links pointing back to Headlines.com. For an extra fee, subscribers may harvest the actual story bodies from Headlines.com and thus keep the traffic on their own site instead of linking back to Headlines.com.

2.1.2 Parts Scenario

Each item in the JetSharp parts catalog consists of some structured data, such as price, shipping weight, and size, and also contains unstructured data consisting of a set of HTML files and GIF images describing the product.

The JetSharp catalog is huge, but, fortunately, changes fairly slowly over time.

2.2 Protocol Overview

There are several key concepts that form the foundation of the ICE protocol. They are introduced here, without regard to their spelling (i.e., how they appear in the protocol). The next chapter (3.0 Protocol Infrastructure) revisits these concepts, and more, with a complete description of the protocol format. But first it is important to understand the basic concepts.

2.2.1 Payloads, Requests, and Responses

Payloads can contain requests, responses or unsolicited messages. The unsolicited messages are used to support Minimal Subscriber implementations and will be explained in that context, later (see 2.2.4). A request is a message asking for the performance of an operation, and a payload is used to transmit the request. For example, when a Subscriber wishes to initiate a relationship by obtaining a catalog from a Syndicator, the Subscriber sends the Syndicator a payload containing a "get catalog" request. Similarly, a response is a message containing the results of an operation and a payload is also used to transmit responses.

2.2.2 Request/Response model

There are a few operations in ICE that have no logical requirement for a response. Nevertheless, to preserve the nature of the request/response protocol, responses are returned anyway.

2.2.3 Subscriber/Syndicator, Requester/Responder, Sender/Receiver

The definition of Subscriber and Syndicator is based on the business relationships: the Syndicator distributes content to the Subscriber. These terms are capitalized throughout this specification wherever they refer specifically to the roles of the parties in an ICE relationship, as opposed to the general concepts of subscribing and syndicating.

The definition of Requester/Responder is based on who initiates the ICE operation. The initiator is the Requester, and the other party, who performs the operation, is the Responder. It is possible for a Syndicator to be either a Requester or a Responder, depending on the particular operation. The same is true for a Subscriber. For example, when a Subscriber initiates a "get catalog" request to a Syndicator, the Subscriber is the Requester. When a Syndicator initiates a "push package update" request to a Subscriber, the Syndicator is the Requester.

Finally, the concept of Sender and Receiver are used in this specification to describe the relationship with respect to the transmission of a single payload. A payload travels from Sender to Receiver (and this thus forms the definition of Sender and Receiver).

Note that an ICE operation inherently consists of a Request/Response pair. Thus, the Requester starts out being a Sender, sending a payload, containing a request, to the Receiver. The Receiver of this first payload is the Responder. When the Responder has performed the operation and wishes to return the results, the Responder becomes the Sender of a payload containing the response, and the initial Requester is now the Receiver.

2.2.4 Minimal Subscriber Implementation and Unsolicited Message

Thus, in a Minimal Subscriber implementation, the Subscriber always initiates any communication, and therefore the Syndicator cannot initiate any communication to the Subscriber. In that case the Subscriber is always the Requester, and never the Responder. However, sometimes a Syndicator needs to initiate a message to a Subscriber. For example, the Syndicator might wish to send a "notify" message containing warning that the system will be down next week.

To support Minimal Subscribers and yet still allow Syndicators to initiate requests, ICE defines a mechanism called the Unsolicited Message mechanism. This mechanism supports sending ICE requests from a Syndicator to the Subscriber in a protocol communication initiated by the Subscriber.

As will be seen later when unsolicited messages are explained in detail, the unsolicited message mechanism is largely orthogonal to the primary ICE request/response protocol mechanism. It is defined as an additional set of message types that can be carried by payloads, and as such can be understood separately. See section 3.10, Unsolicited Message Operation for more details. For explanatory purposes, most of this specification ignores the implication of the unsolicited message mechanism when explaining how ICE works; section 3.10 then describes in detail how the unsolicited message mechanism interacts with the rest of ICE. It is important to note, however, that support for unsolicited messages is not optional; all ICE Subscribers and Syndicators MUST implement the unsolicited message mechanism as described in this specification.

2.3 Binding of ICE to HTTP

This section describes the specifics of how ICE payload exchange is performed using HTTP.

2.3.1 Use of HTTP POST

2.3.2 Mapping the ICE Request/Response Model to HTTP POST/Response

As will be shown in detail later, ICE requests are specified using an ice-request XML element, and ICE responses are specified using an ice-response element. For ICE/HTTP, the ice-request MUST be sent in an HTTP POST, and the ice-response to that request MUST be sent in the HTTP Response to that POST. Thus, a single ICE request/response pair always maps directly to a single HTTP POST/Response pair.

Operations involving package transmission can ask for an additional confirmation, i.e., a third message (request/response/confirmation). In that case the confirmation message is actually a separate request with its own response, so the physical realization of (request/response/confirmation) is actually (request/response/request/response). This will be explained in more detail in the confirmation section, for now it suffices to understand that a confirmation message is simply POSTed as another ice-request.

An example will help illustrate this. Consider package update: the Subscriber makes a "get package" request to the Syndicator, the Syndicator sends a "package" response, and if the Syndicator asks for confirmation then the Subscriber sends a second "confirmation" request.. In a pseudo-code representation of the protocol, the exchanges look like the following. Note, this is pseudo-code, it does not represent the actual protocol format. (The symbol, "==>", can be read as, "sends the following message to the" and the symbol, "<==",  can be read as "receives the following message from the"):

(1) SUBSCRIBER ==> SYNDICATOR:
    HTTP POST:
      <ice-payload>
         <ice-request> 
           Get Package
         </ice-request>
      </ice-payload>


(2) SUBSCRIBER <== SYNDICATOR:
    HTTP Response to the POST:
      <ice-payload>
         <ice-response> 
            Package: X
            Confirmation Required
         </ice-response>
      </ice-payload>

This exchange of an ice-request and an ice-response occurs entirely within a single HTTP POST/Response transport level transaction.

(3) SUBSCRIBER ==> SYNDICATOR:
    HTTP POST:
      <ice-payload>
         <ice-request> 
            Confirmation of Package X
         </ice-request>
      </ice-payload>


(4) SUBSCRIBER <== SYNDICATOR:
    HTTP Response to the POST:
      <ice-payload>
         <ice-response> 
         </ice-response>
      </ice-payload>

A confirmation message is a request that (logically) needs no response, other than the "acknowledge" necessary to maintain the request/response nature of the ICE protocol.

2.3.3 Multiple Requests in a Single Payload

Four key restrictions about the multiple request/response model must be clearly understood:

1. Placing multiple ice-request elements in a single ice-payload does not imply any ordering or transactional semantics. A Sender MUST assume the Receiver processes the requests in an arbitrary order, AS-IF each request had been sent separately in its own payload.
2. A Sender MUST NOT mix ice-request elements and ice-response elements within a single ice-payload.
3. The number of ice-response elements in a response payload MUST be the same as the number of ice-request elements in the initiating payload, with the sole exception to this rule being errors and conditions related to the entire payload, as explained in the discussion of 3xx Payload Level Status Codes in section 3.4.4 (Defined Status Codes).
4. Each ice-response element in a response payload MUST be a response to an ice-request element in the initiating payload.

2.3.4 Content Type in HTTP Header

3. Protocol Infrastructure

3.1 Syntax and Format

3.1.1 XML Syntax

This document does not repeat the general rules for proper XML encoding; readers are expected to refer to the XML specification.

3.1.2 Generic Rules for Attribute Formats

• Unless explicitly indicated otherwise, leading and trailing white space characters in attribute values MUST be ignored. For example, the following two attribute values are equivalent:

  "equivalent"

  " equivalent "

• When an attribute value is a numeric quantity, implementations MUST accept any form permitted by the C strtol() function definition as defined in the ISO C standard.

3.2 Identifiers

3.2.1 Subscriber and Syndicator Identifiers

The UUID format as specified consists of 32 hexadecimal digits, with optional embedded hyphen characters. Per the requirements in the Universal Unique Identifier specification, ICE implementations MUST ignore all hyphens when comparing UUID values for equality, regardless of where the hyphens occur. Also, note that comparisons MUST be case insensitive.

3.2.2 Other Identifiers

The table below describes each identifier in ICE, its scope, a description of where in an ICE payload the ID value is assigned, the role of the party that assigns the ID value, where this ID value is referenced, and finally, the section in the specification where the identifier is discussed.
 
 

Identifier	Scope	Where assigned	By Whom Assigned	ID Referenced By	Section described in
Syndicator's UUID	Unique identifier of  a Syndicator	When ICE syndicator created	Entity wishing to use ICE to Syndicate Content. See 3.2.1 above	sender-id attribute on ice-sender element or receiver-id attribute on ice-receiver element (depending on role)	3.6.1, 3.6.2, 6.3
Subscribers UUID	Unique identifier of  a Subscriber	When ICE subscriber created	Entity wishing to use ICE to Subscribe to Content.  See 3.2.1 above.	sender-id attribute on ice-sender element or receiver-id attribute on ice-receiver element (depending on role)	3.6.1, 3.6.2, 6.3
payload ID	Unique across all payloads from a sender to a receiver	payload-id attribute on ice-payload element	Sender assigns.  See 3.5.2	payload-id attribute on ice-code element	3.4.2, 3.5.2
package ID	Unique across all packages within a subscription	package-id attribute on ice-package element	Syndicator assigns.  See 5.2.1	package-id attribute on ice-code, ice-package-state elements	3.4.2, 5.2.1, 5.5.2
request ID	Unique across all payloads from a sender to a receiver	request-id attribute on ice-request, ice-unsolicited-now elements	Sender assigns.  See 3.7.1	message-id attribute on ice-code element; request-id attribute on ice-event-msg element	3.7.1, 3.10.2, 6.3
response ID	Unique across all payloads from a  sender to a receiver	response-id attribute on ice-response element	Sender assigns.  See 3.7.2	response-id attribute on ice-event-msg element	3.7.2, 6.3
unsolicited request ID	Unique across payloads from a  sender to a receiver	unsolicited-request-id attribute on ice-unsolicited-request element	Syndicator assigns.  See 3.10.3	message-id attribute on ice-code element; request-id attribute on ice-event-msg	3.10.3, 6.3
unsolicited response ID	Unique across payloads from a sender to a receiver	unsolicited-response-id attribute on ice-unsolicited-response element	Subscriber assigns.  See 3.10.4	response-id attribute on ice-event-msg	3.10.4, 6.3
subscription ID	Unique across subscriptions from a Syndicator to a Subscriber	subscription-id attribute on ice-subscription element	Syndicator assigns.  See 4.3.1 and 4.6.3	subscription-id attribute on ice-cancel, ice-change-subscription,  ice-get-events, ice-get-package, ice-get-sequence, ice-get-status, ice-repair-item, ice-send-confirmation, ice-cancellation, ice-events, ice-sequence, ice-subscription, ice-offer, ice-package, ice-event-msg elements	4.3.1, 4.6.1, 4.6.2, 4.6.3. 5.2.1. 5.3, 5.5.1, 5.5.2, 5.5.3, 6.2, 6.3
cancellation ID (see note in 4.6.1)	Unique across all cancellations	cancellation-id attribute on ice-cancellation element	Responder assigns.  See 4.6.1	Not referenced deprecated	4.6.1
package sequence ID	Unique across all packages of a subscription, or "ICE-INITIAL" or "ICE-ANY"	new-state attribute on ice-package element	Syndicator assigns.  See 5.1.3	current-state attribute on ice-get-package, ice-get-sequence, ice-repair-item, ice-subscription, elements; old-state attribute on ice-package element	5.1.3
item ID	Unique across items in a package	item-id attribute on  ice-item, ice-item-ref elements	Syndicator assigns. See 5.2.2.1	Not referenced	5.2.2.1
subscription element ID	Unique within a subscription	subscription-element attribute on ice-item, ice-item-ref, ice-item-group elements	Syndicator assigns.  See 5.2.2.1	subscription-element attribute on ice-repair-item, ice-item-remove elements	5.2.2.1, 5.2.2.2, 5.2.2.3, 5.2.3
item group ID	Unique across all group-items in a package	item-group-id attribute on ice-item-group element	Syndicator assigns.  See 5.2.2.3	Not referenced	5.2.2.3
extension UUID	Universally Unique Extension identifier	UUID attribute on ice-extension element	Syndicator or Subscriber assigns. See 4.5.5 (ice-extension)	ICE application processor uses UUID to obtain an extension.	4.5.5 8.4.1
offer ID	Unique within the catalog of offers made by a Syndicator to a Subscriber.	offer-id attribute on ice-offer element	Syndicator assigns.	ICE processor MAY use it to verify received offers.	4.3.2
ID	Payload-wide (XML document) unique identifier	id attribute on ice-access, ice-negotiable, ice-range, ice-range-define, ice-span, ice-span-max, ice-span-min, ice-span-point, ice-default-value, ice-enum, ice-enum-item, ice-limit and ice-extension elements	Syndicator or Subscriber assigns. See 4.5	ref attribute on ice-access, ice-span, ice-default-value, ice-span-max, ice-span-min, ice-span-point, ice-enum, ice-enum-item, and ice-limit	5.2.2.2 4.5.2 4.5.3 4.5.4

Many attributes in ICE contain as values the identifiers described above and use them to track and signal specific states in the syndication relationship.  The table below describes the attributes that contain the identifiers described in the table above.
 

Attribute containing an Identifier	Identifier Contained	Spec. Reference
sender-id	Syndicator's UUID or Subscribers UUID	3.5.1
receiver-id	Syndicator's UUID or Subscribers UUID	3.5.2
message-id	request-id or response-id	3.3.2
old-state	package-sequence-id	5.1.4
new-state	package-sequence-id	5.1.4
current-state	package-sequence-id	5.3
sequence-id	package-sequence-id	5.5.2
other-id	Syndicator's UUID or Subscribers UUID	6.3
ref	element identifier to access and use previously defined elements such as ice-span, ice-span-max, ice-span-min, ice-span-point, ice-default-value, ice-enum, ice-enum-item or ice-limit	4.5.2 4.5.3 4.5.4

3.3 Dates and Times

3.3.1 ICE Date Format

   CCYY-MM-DD

Note that specifying a Date without a time rarely makes sense because of time zones (without a time attached to a Date it is hard to know exactly what the Date really means); see 3.3.5 for how to specify both in an ICE DateTime format. No fields defined by ICE have been defined to be "naked" dates; ICE always uses the DateTime format.

3.3.2 ICE Time Format

    hh:mm:ss

  00:00:00 (midnight behind or current)
  24:00:00 (midnight ahead -- i.e. 00:00:00 tomorrow )  

Note alternatively, that 00:00:00 on one day is the same time as 24:00:00 on the previous day. This is deliberate, and in accordance with [ISO8601] section 5.3.2.

3.3.3 Sub-second Resolution

    hh:mm:ss,s

3.3.4 Time Zones

3.3.5 ICE Date and Time Format

    CCYY-MM-DDThh:mm:ss,s

Senders MUST NOT specify invalid combinations of fields, such as February 31. Receivers SHOULD reject invalid combinations of fields, rather than trying to interpret them.

3.3.6 ICE Duration Format

    PnS

To describe a period of time with sub second granularity, the format is:

     Pn,nS

All periods of time described as being in ICE Duration Format in ICE MUST be specified in either the PnS or Pn,nS format.

Note that long periods of time are represented by large quantities of seconds in the above formats. For example, a period of one day is P86400S. It is expected that implementations will translate these time periods into a more familiar form as part of their user interfaces.

3.4 Status and Error code formats

3.4.1 No HTTP Relationship

Throughout the rest of this discussion, an HTTP status of "200 OK" is implicit for the transport of the ICE payloads.

3.4.2 Status Code Format

An example would be:

  <ice-code 
        numeric="402" 
        phrase="Not well formed XML"
        message-id="1998-07-01T11:34:10@nr3.com-1"
  >
  Your XML contained overlapping elements.
  Here is the offending fragment: 
       &lt;a&gt;&lt;b&gt;cdefg&lt;/a&gt;&lt;/b&gt;
  </ice-code>

The attributes are:

• numeric
  REQUIRED. Three digit status code, as explained further below.
• phrase
  REQUIRED. Simple error descriptive text, as explained further below.
• payload-id
  CONDITIONAL. The payload-id of the payload referenced by this code. A Sender SHOULD supply this when reporting a payload level (3xx) code, and MUST NOT supply it any other time. See further discussion of payload errors
• message-id
  CONDITIONAL. The request-id of the request referenced by this code, or, in some cases, the response-id of the response referenced by this code. A Sender MUST supply this in all cases except when reporting a payload level (3xx) code.
• package-id
  CONDITIONAL. The package-id of the package referenced by this code. A Sender MUST supply this when issuing a confirmation or a surprise code (see 3.8) that refers to a package
• xml:lang
  OPTIONAL. The language of the free-form text contained in the ice-code.

3.4.3 Body

Implementation note: it is very important to properly escape any fragments reported in the body of the ice-code. See, for example, the example shown in 3.4.2. Note in particular that XML and HTML (and, more generally, any text containing angle brackets and other syntactically significant characters) must be properly escaped.

3.4.4 Defined Status Codes

When generating codes:

• Senders MUST supply a three digit numeric value from the set defined here.
• Senders MUST supply the phrase field (enforced by the DTD).
• Senders SHOULD use the exact phrase shown in the list below.

• Receivers MUST understand all the three digit codes described in this specification.
• Receivers MUST NOT use the phrase data for any purpose other than as informational data with no defined semantics. A typical use for the text string is to display it on a console, or put it into a log file for later analysis by humans.
• Receivers MUST NOT use the free-form body of the ice-code element for any purpose other than as informational data with no defined semantics.
• Receivers MAY treat unrecognized codes not defined in the ICE specification, or 9xx codes, in an implementation specific manner. As a quality of implementation issue, receivers could implement user interfaces allowing customized handling or mapping of unknown codes to specific actions; however, this specification does not require them to do so.

The status values defined by ICE are:

2xx: Success

• 200 OK
  The operation completed successfully.
• 201 Confirmed
  The operation is confirmed. See Section 3.8 Confirmation for a discussion.
• 202 Package sequence state already current
  A Subscriber requested a package update, but the Subscriber is already in the current package sequence state, i.e., there are no updates at the moment.

3xx: Payload level Status Codes

These indicate something about the ice-payload itself, as opposed to the individual requests and responses within the payload. These codes have one very explicit and important semantic: they are used when the payload could not be properly interpreted, meaning that even if there were multiple requests in the payload, there will be only one ice-code in the response. For example, if the payload had been corrupted, it might be so corrupted that it isn't even possible to determine how many requests it contains, let alone respond to them individually.

The specific codes are:

• 300 Generic catastrophic payload error
  Generic status code indicating inability to comprehend the received payload. Usually, it is better to send a more specific code if possible.
• 301 Payload incomplete/cannot parse
  The payload sent is severely garbled and cannot be parsed. For example, if a binary file were sent instead of an XML payload, this would be an appropriate response.
• 302 Payload not well formed XML
  The payload sent is recognizable as XML, but is not well formed per the definition of XML. This is available as both a payload level error and as a request level (4xx) error. Whether a given implementation attempts to interpret not well formed XML so as to generate request level (4xx) errors versus payload level (3xx) errors is a quality of implementation issue.
• 303 Payload validation failure
  The payload failed validation according to the DTD. This is available as both a payload level error and as a request level (4xx) error. Whether a given implementation attempts to interpret not well formed XML so as to generate request level (4xx) errors versus payload level (3xx) errors is a quality of implementation issue. Note that Receivers SHOULD perform validation on incoming ICE payloads, but are not required to. Senders MUST send only valid ICE payloads or they are in error; however, the ability to detect invalid payloads is a quality-of-implementation issue for the Receiver, and Senders MUST NOT assume the Receiver will perform an XML validation on their payloads.
• 320 Incompatible version
  The ICE protocol version used in the request is not supported. NOTE: The ICE protocol versions are transmitted as part of the payload header, implementations may look there to decide what appropriate corrective actions to take. Implementations must follow the version rules defined in Appendix B. For a discussion of ICE versions see also ice.version in section 3.5.2, Payload Element Definition
• 331 Failure fetching external data
  The receiver could not follow an external reference (URL) given to it by the sender as an external entity reference.  Note that in ICE 1.0 and ICE 1.1 only the Subscriber is permitted to reply with this code.  A Syndicator MUST NOT reply with this code.
• 390 Payload temporary redirect
  Used with redirection; see 3.4.5.
• 391 Payload permanent redirect
  Used with redirection; see 3.4.5.

4xx: Request level Status Codes

These indicate errors caused by an inability to carry out an individual request. Note that in some cases there are similar errors between the 3xx and 4xx class; the difference is whether or not the error is supplied as a single, payload level error code (3xx) or whether it is supplied as a prerequisite code.

• 400 Generic request error
  Generic status code indicating inability to comprehend the request. Usually, it is better to send a more specific code if possible.
• 401 Incomplete/cannot parse
  The request sent is severely garbled and cannot be parsed. Note that in most cases, a payload level error (301) might be more appropriate.
• 402 Not well formed XML
  The request sent is recognizable as XML, but is not well formed per the definition of XML. This is available as both a payload level error and as a request level (4xx) error. Whether a given implementation attempts to interpret not well formed XML so as to generate request level (4xx) errors versus. payload level (3xx) errors is a quality of implementation issue.
• 403 Validation failure
  The request failed validation according to the DTD. This is available as both a payload level error and as a request level (4xx) error. Whether a given implementation attempts to interpret not well formed XML so as to generate request level (4xx) errors versus. payload level (3xx) errors is a quality of implementation issue. Note that Receivers SHOULD perform validation on incoming ICE payloads, but are not required to. Senders MUST send only valid ICE payloads or they are in error; however, the ability to detect invalid payloads is a quality-of-implementation issue for the Receiver, and Senders MUST NOT assume the Receiver will perform an XML validation on their payloads.
• 404 This error intentionally left blank
• 405 Unrecognized sender
• 406 Unrecognized subscription
• 407 Unrecognized operation
• 408 Unrecognized operation arguments
• 409 Not available under this subscription
  The Requester has referenced something not covered by the subscription referenced in the request.
• 410 Not found
  Generic error for being unable to find something.
• 411 Unre