Default HTTP Binding

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

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:

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.

Consistent with the event traces that characterise the mep:single-request-response transport message exchange pattern [ref] the transfer of both Request and Response Messages MAY overlap in time at both Requesting and Responding nodes, however the transfer of a Request Message MUST commence prior to beginning the transfer of the Response Message.

3.1.1    Behaviour of Requesting SOAP Node

A requesting SOAP node forms a Request Message for transmission as follows:

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.

During reception of an HTTP response, any HTTP headers that are significant to features expressed outside the SOAP envelope are processed in accordance with the relevant feature specification eg. SOAPAction (see section 4).

During reception of an HTTP response the following transport message exchange context properties may be instantiated or overwritten:

Instantiated or replaced Property Value
transport:ImmediateSender a URI value that denotes the sender of the HTTP response (if known)
transport:CurrentMessage a value that represents the received Response Message
transport:FailureReason (see following table)

Event/Condition (non-Exhaustive) Failure Reason
Transmission Failure (broken connections etc.) fail:TransmissionFailure
Reception Failure (broken connections etc.) fail:ReceptionFailure
Packaging Failure (inc. mismatched Content-Type) fail:PackagingFailure
Malformed Response Message, eg malformed XML, invalid SOAP Envelope fail:BadResponseMessage

The following table details any SOAP specific interpretation of returned HTTP status codes.

[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
2xx Successful  
200 OK

The Response Message follows in HTTP response entity body.

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.

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.

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.

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.

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

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.

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.

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.

Instantiated or replaced Property QName Property Value
transport:FaultHint true

3.1.2    Behaviour of Responding SOAP Node

During reception of an HTTP request, any HTTP headers that are significant to features expressed outside the SOAP envelope are processed in accordance with the relevant feature specification eg. SOAPAction (see section 4).

During reception of an HTTP request and transmission of the corresponding HTTP response the following transport message exchange context properties may be instantiated or overwritten:

Instantiated or replaced Property Value
transport:ImmediateSender a URI value that denotes the sender of the HTTP response (if known)
transport:CurrentMessage a value that represents the received Request Message
transport:FailureReason (see following table)

Event/Condition (non-Exhaustive) Failure Reason
Transmission Failure (broken connections etc.) fail:TransmissionFailure
Reception Failure (broken connections etc.) fail:ReceptionFailure
Packaging Failure (inc. mismatched Content-Type) fail:PackagingFailure
Malformed Response Message, eg malformed XML, invalid SOAP Envelope fail:BadResponseMessage

Specific problems with the in bound HTTP request message may make it impossible to recover the Request Message from the HTTP request message. In the event of such failures the following table details the HTTP status codes and SOAP Fault message (if any) that SHOULD be used in forming the HTTP response.

[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

During Request Message processing in the responding SOAP Node replaces the contents of the transport:CurrentMessage in the transport message exchange context  with a value that represents the corresponding Response Message.

A responding SOAP node formulates an HTTP response as follows:

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 ??  

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 <">