Default HTTP Binding

Status

This is an attempt of a write-up of a default HTTP binding based on discussions within the XML Protocol WG TBTF. The document has no status whatsoever nor does it necessarily represent consensus within the TBTF or within the XML Protocol WG as a whole.

0    Introduction

This SOAP binding specification adheres to the SOAP Binding Framework ([ref to binding framework]), and as such uses abstract properties as a descriptive tool for defining the functionality of certain features.

Properties are named with XML qualified names (QNames).

Property values are determined by the Schema type of the property, as defined in the specification which introduces the property.

Standard Prefix Mappings

The following are standard prefix mappings which we assume to hold throughout this document.

1    Binding Name

The binding described here is identified with the URI:

• http://www.w3.org/2001/09/soap/bindings/defaultHTTP/

The binding described here is provided as a default binding when using HTTP as the underlying protocol. 

2    Supported Transport Message Exchange Patterns

An instance of a transport binding to HTTP [RFC2616] conforming to this transport binding specification MUST support the following transport message exchange pattern:

•    http://www.w3.org/2001/09/soap/transport-mep/single-request-response/    (see [ref to mep description])

Here I think we should say that the request part is mapped to a HTTP request and the response to a HTTP response - obvious but worth saying.

3    Message Exchange Operation

The Transport Binding Framework [ref], Transport Message Exchange Pattern Specifications eg [ref] and Feature Specifications eg [ref] each describe the properties they expect to be present in a transport message exchange context when control of that context is passes between the local SOAP Node and a binding instance and vice versa.

3.1    Single Request-Response Exchanges 

The http://www.w3.org/2001/09/soap/transport-mep/single-request-response/ transport message pattern is described in [ref to mep description].

For binding instances conforming to this specification:

• A SOAP Node instantiated at an HTTP client may take on the role (i.e. the property single:Role) of RequestingSOAPNode.
• A SOAP Node instantiated at an  HTTP server may take on the role (ie. the property single:Role) of RespondingSOAPNode.

The remainder of this section consists of descriptions of the MEP state machine, and its particular relation to the HTTP protocol. In the state tables below, the states are defined as values for the property "single:State" [ref to MEP], and are of type "single:StateType" (an enumeration over xsd:string).

Failure reasons as specified in the tables represent values of the property "transport:FailureReason" - their values are QNames. If an implementation enters the "Fail" state, the transport:FailureReason property will contain the value specified for the particular transition.

3.1.1    Behaviour of Requesting SOAP Node

The overall flow of the behaviour of a Requesting SOAP Node follows the outline state machine description contained in [ref single-request-response tmep decription].

[skw] std included here, some suggest we should include it here, others suggest referencing the mep description and avoiding the repetition

[skw] Preconditions for entering this first state should be part of the single request response mep description

3.1.1.1 Requesting State

[skw] Note that we have said nothing about attachments here. The simple interpretation is that this binding does not support attachments. I think that we could do further work to abstract message encapsulation as a feature... in which case we would have some properties that would influence the selection of content type in the second step above and which would influence the message serialisation.

3.1.1.2 Waiting State

The following table details the HTTP status code dependent transitions upon reception of an HTTP status line and response headers.

[skw] This is a large table and it would be good shrink it somewhat. It doesn't cover all generally possible HTTP status codes and may cover more than it should. This is one that we should be able to address provided the direction and style are to people's taste.

[gd] Do we need the "*xx" rows at all?

3.1.1.3 Receiving

3.1.1.4 Success and Fail

These are the terminal states of for a given instance of a single-request-response transport message exchange. Control over the transport message exchange context returns to the local SOAP node.

3.1.2    Behaviour of Responding SOAP Node

The overall flow of the behaviour of a Requesting SOAP Node follows the outline state machine description contained in [ref single-request-response tmep decription].

[skw] std included here, some suggest we should include it here, others suggest referencing the mep description and avoiding the repetition

[skw] Preconditions for entering this first state should be part of the single request response mep description. The receiving binding brings a transport message exchange context into existence for the inbound message instantiates it in a generic receiving state.

3.1.2.1 Receiving

[skw] As described this model tends to hide a malformed message from the local SOAP Node and handle the malformation in the binding - basically because it would not be possible to instantiate the CurrentMessage to pass up for processing. An alternate formulation might be to allow CurrentMessage to carry badly formed messages and let the SOAP processor/node deal with it. As presented here we can have define the bindings behaviour with respect to particular failures.

[skw] This is intended to be aligned with Chris Ferris's proposal on Issue #12. There is a long and interesting thread that may influence how this is presented

3.1.2.2 Processing

3.1.2.3 Responding

3.1.2.4 Success and Fail

These are the terminal states of for a given instance of a single-request-response transport message exchange. From the point-of-view of the local node this message exchange has completed.

3.1.3    Operation Through SOAP Intermediaries

[skw] I (currently) think that operation of a given MEP through an intermediary is something that needs to be part of the MEP description, rather than part of a binding description.

4    Features Expressed External to the Message Envelope

This transport binding specification defines a binding specific expression for the following features:

• http://www.w3.org/2001/09/soap/bindings/defaultHTTP/SOAPAction/

Other features that are compatible with the message exchange patterns listed above are supported using their generic in-envelope expression defined in the relevant feature specification.

4.1    SOAP Action

This sub-section defines a binding specific optional feature named:

• http://www.w3.org/2001/09/soap/binding/defaultHTTP/SOAPAction/

Feature Description

Some SOAP Receivers using this binding might need certain information to be readily available outside the message envelope. This binding uses an externalised expression of the SOAP Action feature to supply this information.

Use of the SOAP Action feature is OPTIONAL. SOAP Receivers MAY use it as a hint to optimise processing, but SHOULD NOT require its presence in order to operate. Support for SOAPAction is OPTIONAL in implementations. Implementations SHOULD NOT generate or require SOAPAction UNLESS they have a particular purpose for doing so (e.g., a SOAP Receivers specifies its use).

Feature Properties

Feature Operation

The action:SOAPActionURI and action:RequiredSOAPActionURI properties are represented in HTTP using the HTTP headers SOAPAction and Required-SOAPAction respectively. The following table shows the points at which the property values and HTTP header values are exchanged.

HTTP Header Syntax

The syntax for the SOAPAction and Required-SOAPAction HTTP headers fields is defined as follows:

SOAP Action HTTP Header:

Required SOAP Action HTTP Header: