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.
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 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.
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.
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
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.
Statename | Waiting | ||
Preconditons | None | ||
Description | Wait for HTTP Response | ||
Actions on Leaving State |
|
||
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 |
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 |
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.
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.
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 |
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
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 |
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 | ?? |
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.
[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.
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 <"> |