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.
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/ |
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.
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.
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.
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 | ||
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 | ?? |
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.
This sub-section defines a binding specific optional feature named:
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 <"> |