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.

Prefix Namespace
transport http://www.w3.org/2001/09/soap/bindingFramework/TransportExchangeContext/
mep http://www.w3.org/2001/09/soap/transport-mep/
fail http://www.w3.org/2001/09/soap/transport-mep/FailureReasons/
single http://www.w3.org/2001/09/soap/transport-mep/single-request-response/

1    Binding Name

The binding described here is identified with the URI:

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:

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.

The Transport Binding Framework [ref] , Transport Message Exchange Specifications eg. [ref] and Feature Specifications, describe the preconditions applied during the transfer of control of a transport message exchange context between a SOAP Node and a local binding instance. Application of these preconditions resolve the transport message exchange pattern in operation, the role of the local SOAP Node with respect to the exchange pattern and that the transport message exchange context contains the property values necessary to the operation of any active features.

[gd] I think that this paragraph could profitably be rewritten in more straightforward language, and perhaps belongs more aptly in the framework doc itself, rather than the binding.

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:

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.

[gd] The single:Role property is an enumeration over xsd:string, with at least the two values above, defined in the MEP spec. As indicated, the states and states property are also defined in the MEP spec.

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].

Requesting SOAP Node State Transition Diagram

[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
Statename Requesting
Preconditons See [ref section of mep description]
Description Formulate and send  HTTP Request (see table below)
Actions on Leaving State  
   
Transitions Event/Condition NextState Failure Reason
Successfully sent HTTP Request Waiting N/A
Failure to send HTTP Request Fail fail:TransmissionFailure

HTTP Request Fields  
HTTP Method POST (the use of other HTTP methods is currently undefined in this binding).
Request URI The value of the URI carried in the transport:ImmediateDestination property of the transport message exchange context.
Content-Type header "text/xml" according to RFC 2376[ref]
Additional Headers Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange eg. SOAPAction (see section 4).
HTTP entity body XML 1.0 serialisation of the SOAP message XML Infoset carried in the transport:CurrentMessage property of the transport message exchange context.

[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
Statename Waiting
Preconditons None
Description Wait for HTTP Response
Actions on Leaving State
  • Instantiate or replace the property transport:ImmediateSender with a URI value that denotes the sender of the HTTP response (if known)
  • In all cases, any HTTP headers that are significant to features expressed outside the SOAP envelope are processed in accordance with the relevant feature specification.

   
Transitions Event/Condition NextState Failure Reason
Received HTTP Response Status Line and HTTP Headers (see status code table below) (see status code table below)
Reception Failure Fail fail:ReceptionFailure

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?

HTTP Status Code HTTP reason phrase (informative) Significance/Action NextState
2xx Successful    
200 OK

The Response Message follows in HTTP response entity body.

Receiving
202 Accepted The Request Message has been received and processed. Then entity body of the HTTP response MAY contain a Response Message.

[skw] Don't really know what we should do here. HTTP gives guidance on what should be in the entity body, but seemingly in terms of what information you might present to the user of the user-agent. One could provide semantically similar information within a SOAP Response Message - in which case this follows the RR pattern. Alternatively, the HTTP entity body could be 'empty' (in which case 202 should be used) or may not contain a SOAP message (to be picked up later....]. We could define that the default HTTP binding never returns this status code (perhaps).

 
204 No Content

The Request message has been received and processed. The HTTP response MUST NOT contain an entity body. The transport message exchange is regarded as having completed successfully.

[skw] This seems to have turned RR into single direction one-way (client to server). ie. this breaks the request-response pattern. Could take the view that this status code is an error when engaged in a single-request-response exhange or a short-hand for an empty Response Message - ie. a Response-Message that is just an empty envelope as opposed to no-response.

Success
Instantiated or replaced Property QName Property Value
transport:CurrentMessage Replace contents with a value that represents and empty SOAP Envelope.
transport:ImmediateSender If known instantiate this property with a URI denoting the sender of the HTTP response.
3xx Redirection The requested resource has moved and the HTTP request SHOULD be retried using the URI carried in the associated Location header as the request-URI for the POST request.

[skw] RFC2616 states that these response codes SHOULD NOT be handled automatically except when the request method is GET or HEAD (which is not the case for this binding). Otherwise it suggests that the user should be involved in handling the redirection. Certainly looks like 301, 302, 303, 305  and 307 may be amenable to automatic processing - in which case I think that the entity body of the HTTP response should be discarded and the HTTP request message resend with a Request-URI taken from the Location header of this response.

Requesting
4xx Client Error    
400 Bad Request

Indicates a problem with the received HTTP Request Message. This may include a malformed XML in the Request-Message envelope. This operation SHOULD NOT be repeated with the same message content. The transport message exchange is regarded has having completed unsuccessfully.

Fail
Instantiated or replaced Property QName Property Value
transport:FailureReason fail:BadRequest
401 Unauthorized Indicates that the HTTP Request requires authorization. If available this engages the Simple Authentication feature specified in [ref Simple Authentication Feature ]

[skw] At present this is more of a hook, we have not (yet) described a simple authentication feature or an HTTP specific expression of that feature.

Requesting
Instantiated or replaced Property QName Property Value
transport:FailureReason fail:AuthenticationFailure
If the simple authentication feature is unavailable or the operation of simple authentication ultimately fails, then the transport message exchange is regarded as having completed unsuccessfully.

Fail

Instantiated or replaced Property QName Property Value
transport:FailureReason fail:AuthenticationFailure
405 Method not allowed

Indicates that the peer HTTP server does not support the requested HTTP method at the given request URI. The transport message exchange is regarded has having completed unsuccessfully.

Fail
Instantiated or replaced Property QName Property Value
transport:FailureReason fail:BindingMismatch
415 Unsupported Media Type

Indicates that the peer HTTP server does not support Content-type used to encode the Request Message. The transport message exchange is regarded has having completed unsuccessfully.

Fail
Instantiated or replaced Property QName Property Value
transport:FailureReason fail:BindingMismatch
427 SOAPAction Required Indicates that the peer HTTP server implements the OPTIONAL SOAPAction feature and that it requires that this node provide a SOAPAction header when resubmitting a similar HTTP request.  The transport message exchange is regarded has having completed unsuccessfully. 

In requesting SOAP nodes that support the OPTIONAL SOAPAction feature, the behaviour described in [ref SOAPAction Feature Spec] is applied.

Fail
5xx Server Error    
500 Internal Server Error

Indicates that the Response Message contained in the following HTTP response entity body may contain an SOAP Fault. Other internal server errors may be the cause of this status code. The local binding instance continues to receive the incoming message.

Receiving
Instantiated or replaced Property QName Property Value
transport:FaultHint true
3.1.1.3 Receiving
Statename Receiving
Preconditons
Description Receive HTTP response entity body.
Actions on Leaving State On transitions to Success, instantiate or replace the property transport:CurrentMessage with a value that represents the received Response Message.
Transitions Event/Condition NextState Failure Reason
Well formed Response Message Received Success  
Reception Failure (broken connections etc.) Fail fail:ReceptionFailure
Packaging Failure (inc. mismatched Content-Type) Fail fail:PackagingFailure
Malformed Response Message, eg malformed XML, invalid SOAP Envelope Fail fail:BadResponseMessage
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].

Responding SOAP Node State Transition Diagram

[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
Statename Receiving
Preconditons Reception of an HTTP POST request at an HTTP endpoint bound to the local SOAP Node.
Description Receive and validate the inbound Request Message 
Actions on Leaving State  
 
Transitions Event/Condition NextState Action
Receive HTTP POST Request containing well formed Request Message. Processing
  • Instantiate or replace the property transport:ImmediateSender with a URI value that denotes the sender of the HTTP request (if known)
  • Instantiate or replace the property  transport:CurrentMessage with a value that represents the received Request Message. 
  • Any HTTP headers that are significant to features expressed outside the SOAP envelope (eg SOAPAction) are processed in accordance with the relevant feature specification. 

This change of state represents a transfer of control of the inbound transport message exchange context to the local SOAP node.

Receive HTTP POST Request that does malformed Request Message Fail The message is deemed to have been intended for the local SOAP node, but is deemed badly formed: ill-formed XML, does contain a valid SOAP envelope. The local SOAP node generates SOAP Fault message in accordance with the table below which it  send in the corresponding HTTP response message, accompanied by a status code value appropriate to the particular fault.

The transport message exchange context may be destroyed or considered not to have been created.

[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.

Problem with Message HTTP Status Code HTTP reason phrase (informative) SOAP Fault
Well-formed XML, unsupported SOAP Envelope Version ??? ??? env:VersionMismatch (see Part 1 Appendix A)
Ill-formed XML or invalid SOAP Envelope (of this SOAP Version) 400 Bad request None
Unsupported message encapsulation method 415 Unsupported Media None

[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
Statename Processing
Preconditons  
Description The SOAP Node processes the  Request Message and replace it a Response Message. 
Actions on Leaving State  
 
Transitions Event/Condition NextState Action or Failure Reason
The local SOAP Node completes the processing of the Request Message.  Responding The SOAP Node replaces the Request Message carried in transport:CurrentMessage with a Response Message. The Response Message may contain a SOAP Fault.
Underlying Connection Failure Fail fail:TransmissionFailure
3.1.2.3 Responding
Statename Responding
Preconditons transport:CurrentMessage contains a value that represents the Response Message (which may contain a Fault).
Description Formulate and send Response Message (see table below)
Actions on Leaving State  
 
Transitions Event/Condition NextState Action or Failure Reason
  The local SOAP Node completes the processing of the Request Message. Responding The SOAP Node replaces the Request Message carried in transport:CurrentMessage with a Response Message. The Response Message may contain a SOAP Fault.

 

HTTP Response Field  
HTTP status line Set according to the following table
Content-Type header "text/xml" according to RFC 2376[ref]
Additional Headers Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange eg. SOAPAction (see section 4).
HTTP entity body XML 1.0 serialisation of the SOAP message XML Infoset carried in the transport:CurrentMessage property of the transport message exchange context.

 

SOAP Fault  HTTP status code HTTP reason phrase (informative)
Non-Fault Response Message 200 OK
env:VersionMismatch ??  
env:MustUnderstand ??  
env:DataEncodingUnknown ??  
env:Client ??  
env:Server ??  
env:rpc ??  
Other Faults ??  
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:

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:

In the text to follow, the prefix "action" is mapped to the URI "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

Property Name Description
action:SOAPActionURI Used to hold the SOAPAction feature value.

The type of this property is anyURI in the http://www.w3.org/2001/XMLSchema-datatypes namespace. Relative URIs are interpreted relative to the Request-URI.

action:RequiredSOAPActionURI If a SOAP Receiver does require the action:SOAPActionURI property in order to operate, it MAY respond to requests which either convey an unrecognised action:SOAPActionURI value or convey no action:SOAPActionURI value with a  response containing an action:RequiredSOAPActionURI property. The SOAP Receiver SHOULD ensure that an HTTP status code of 427 (SOAPAction required) is returned to the corresponding HTTP client.

The type of this property is anyURI in the http://www.w3.org/2001/XMLSchema-datatypes namespace. Relative URIs are interpreted relative to the Request-URI.

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 Client

Property Name Request Response
action:SOAPActionURI If action:SOAPActionURI property is present in the transport message exchange context, it's value is sent as the value of a SOAPAction HTTP header N/A
action:RequiredSOAPActionURI N/A If a  Required-SOAPAction HTTP header is present, it's value is inserted into the transport message exchange context as the value of the action:RequiredSOAPActionURI property.
 

HTTP Server

Property Name Request Response
action:SOAPActionURI If a SOAPAction HTTP header is present, it's value is inserted into the transport message exchange context as the value of the action:SOAPActionURI property. N/A
action:RequiredSOAPActionURI N/A If an  action:RequiredSOAPActionURI property is present in the transport message exchange context, it's value is sent as the value of a Required-SOAPAction HTTP header

HTTP Header Syntax

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

SOAP Action HTTP Header:

[7]   soapaction    =   "SOAPAction" ":" <"> URI-reference <">
[8]   URI-reference    =   <as defined in RFC2396>

Required SOAP Action HTTP Header:

[9]   req-soapaction    =   "required-SOAPAction" ":" <"> URI-reference <">