Copyright © W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
SOAP Version 1.2 provides a request-response MEP and 2 request-response bindings. This provides a 1 way MEP with an optional binding defined response, and a 1 way binding to HTTP request/response that supports SOAP request-response and the 1 way MEP. This specification depends on SOAP Version 1.2 Part 2: Adjuntcts [SOAP-PART2].
This document is an editors' copy that has no official standing.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
1 Introduction
1.1 Notational Conventions
2 SOAP Request Message Exchange Pattern
2.1 SOAP Feature Name
2.2 Description
2.3 State Machine Description
2.4 Fault Handling
3 One-way SOAP HTTP binding
3.1 Introduction
3.1.1 Optionality
3.1.2 Use of HTTP
3.1.3 Interoperability with non-SOAP HTTP Implementations
3.1.4 HTTP Media-Type
3.2 Binding Name
3.3 Supported Message Exchange Patterns
3.4 Supported Features
3.5 MEP Operation
3.5.1 Behavior of Requesting SOAP Node
3.5.1.1 Init
3.5.1.2 Requesting
3.5.1.3 Sending+Receiving
3.5.1.4 Success and Fail
3.5.2 Behavior of Responding SOAP Node
3.5.2.1 Init
3.5.2.2 Receiving
3.5.2.3 Receiving+Sending
3.5.2.4 Success and Fail
3.6 Security Considerations
4 References
4.1 Normative References
4.2 Informative References
A Change Log (Non-Normative)
SOAP Version 1.2 (SOAP) provides a request-response MEP and 2 request-response Bindings. This specification provides a 1 way MEP and a 1 way binding.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].
This specification uses a number of namespace prefixes throughout; they are listed in ???. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).
Prefix | Namespace | Notes |
---|---|---|
env | "http://www.w3.org/2003/05/soap-envelope" | Defined by SOAP 1.2 Part 1 [SOAP Part 1]. |
xs | "http://www.w3.org/2001/XMLSchema" | Defined in the W3C XML Schema specification [XML Schema Part 1], [XML Schema Part 2]. |
Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs (see RFC 2396 [RFC 2396]).
This specification uses the Extended Backus-Naur Form (EBNF) as described in XML 1.0 [XML 1.0].
With the exception of examples and sections explicitly marked as "Non-Normative", all parts of this specification are normative.
This section defines the message exchange pattern (MEP) called "Request". The description is an abstract presentation of the operation of this MEP. It is not intended to describe a real implementation or to suggest how a real implementation should be structured.
This message exchange pattern is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Features):
"http://www.w3.org/2004/12/ws-addr/mep/request/"
The SOAP Request MEP defines a pattern for the exchange of a SOAP message acting as a request optionally followed by a non-SOAP binding specific response. In the absence of failure in the underlying protocol, this MEP consists of one SOAP message and one optional binding specific message:
A request message which contains a SOAP envelope.
An optional response message transmitted in a binding-specific manner that does not include a SOAP envelope and hence does not involve any SOAP processing by the sending SOAP node. The MEP is completed by the processing of binding-specific response message.
Abnormal operation during a Request message exchange might be caused by a failure to transfer the request message, a failure at the responding SOAP node to process the request message, or failure to transfer the optional binding-specific response message. Such failures might be silent at either or both of the requesting and recieving SOAP nodes involved, or might result in the generation of a SOAP or binding-specific fault (see 2.4 Fault Handling). Also, during abnormal operation each SOAP node involved in the message exchange might differ in its determination of the successful completion of the message exchange.
The scope of a Request MEP is limited to the exchange of a request message between one requesting and one responding SOAP node and the exchange of an optional binding specific response message. Implementations MAY choose to support multiple ongoing requests (and associated response processing) at the same time.
The Request MEP defines a set of properties described in ???.
Property Name | Property Description | Property Type |
---|---|---|
http://www.w3.org/2003/05/soap/mep/OutboundMessage | An abstract structure that represents the current outbound message in the message exchange. This abstracts both SOAP Envelope and any other information structures that are transferred along with the envelope. | Not specified |
http://www.w3.org/2003/05/soap/mep/ImmediateDestination | The identifier of the immediate destination of an outbound message. | xs:anyURI |
http://www.w3.org/2003/05/soap/mep/ImmediateSender | The identifier of the immediate sender of an inbound message. | xs:anyURI |
To initiate a message exchange conforming to the Request MEP, the requesting SOAP node instantiates a local message exchange context. ??? describes how the context is initialized.
Property Name | Property Value | Notes |
---|---|---|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName | "http://www.w3.org/2004/12/ws-addr/mep/request/" | |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason | "None" | A relative URI whose
base URI is the value of
|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role | "RequestingSOAPNode/" | A relative URI whose
base URI is the value of
|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State | "Init" | A relative URI whose base URI is the value of
|
http://www.w3.org/2003/05/soap/mep/OutboundMessage | An abstraction of the request message | |
http://www.w3.org/2003/05/soap/mep/ImmediateDestination | An identifier (URI) that denotes the responding SOAP node |
There may be other properties related to the operation of the message exchange context instance. Such properties are initialized according to their own feature specifications.
Once the message exchange context is initialized, control of the context is passed to a (conforming) local binding instance.
The diagram below shows the logical state transitions at
the requesting and responding SOAP nodes during the lifetime
of the message exchange. At each SOAP node, the local binding
instance updates (logically) the value of the
http://www.w3.org/2003/05/soap/bindingFramework/
ExchangeContext/State
property to reflect the current
state of the message exchange. The state names are relative
URIs, relative to a base URI value carried in the
http://www.w3.org/2003/05/soap/bindingFramework/
ExchangeContext/Role
property of the local message
exchange context.
When the local binding instance at the responding SOAP node starts to receive an inbound request message, it (logically) instantiates a message exchange context. ??? describes the properties that the binding initializes as part of the context's instantiation.
Property Name | Property Value | Notes |
---|---|---|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName | "http://www.w3.org/2004/12/ws-addr/mep/request/" | Initialized as early as possible during the life cycle of the message exchange. |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason | "None" | A relative URI whose base URI is the value of http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role | "RespondingSOAPNode" | A relative URI whose base URI is the value of Initialized as early as possible during the life cycle the message exchange. |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State | "Init" | A relative URI whose base URI is the
value of http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role |
When the requesting and responding SOAP nodes transition between states, the local binding instance (logically) updates a number of properties. ??? and ??? describe these updates for the requesting and the responding SOAP nodes, respectively.
CurrentState | Transition Condition | NextState | Action |
---|---|---|---|
"Init" | Unconditional | "Requesting" | Initiate transmission of request message
abstracted in
http://www.w3.org/2003/05/soap/mep/OutboundMessage . |
"Requesting" | Message transmission failure | "Fail" | Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"transmissionFailure" |
Start receiving response message | "Sending+Receiving" | Set
http://www.w3.org/2003/05/soap/mep/ImmediateSender to denote the sender of the response message (may differ from the values in http://www.w3.org/2003/05/soap/mep/ImmediateDestination ).
Start making an abstraction of the response message available in http://www.w3.org/2003/05/soap/mep/InboundMessage . | |
"Sending+Receiving" | Message exchange failure | "Fail" | Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"exchangeFailure" |
Completed sending request message. Completed receiving response message. | "Success" |
CurrentState | Transition Condition | NextState | Action |
---|---|---|---|
"Init" | Start receiving request message | "Receiving" | Set
http://www.w3.org/2003/05/soap/mep/ImmediateSender to denote the sender of the request message (if determinable).
Start making an abstraction of the request message available in http://www.w3.org/2003/05/soap/mep/InboundMessage .
Pass control of message exchange context to SOAP processor. |
"Receiving" | Message reception failure | "Fail" | Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"receptionFailure". |
Start of response message available in http://www.w3.org/2003/05/soap/mep/OutboundMessage | "Receiving+Sending" | Initiate transmission of response message abstracted in http://www.w3.org/2003/05/soap/mep/OutboundMessage . | |
"Receiving+Sending" | Message exchange failure | "Fail" | Set http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"exchangeFailure". |
Completed receiving request message. Completed sending response message. | "Success" |
Bindings that implement this MEP MAY provide for streaming of responses. That is, responding SOAP nodes MAY begin transmission of a binding-specific response while a SOAP request is still being received and processed. When SOAP nodes implement bindings that support streaming, the following rules apply:
All the rules in SOAP 1.2 Part 1 [SOAP Part 1]Binding Framework regarding streaming of individual SOAP messages MUST be obeyed for both request and response SOAP messages.
When using streaming SOAP bindings, requesting SOAP nodes MUST avoid deadlock by accepting and if necessary processing binding-specific response information while the SOAP request is being transmitted.
Note:
Depending on the implementation used and the size of the messages involved, this rule MAY require that SOAP applications stream application-level response processing in parallel with request generation.
A requesting SOAP node MAY enter the "Fail" state, and thus abort transmission of the outbound binding-specific request, based on information contained in an incoming streamed SOAP response.
During the operation of the Request MEP, the participating SOAP nodes may generate SOAP faults.
If a SOAP fault is generated by the recieiving SOAP node
while it is in the "Receiving" state, the SOAP
fault is made available in http://www.w3.org/2003/05/soap/mep/OutboundMessage
and the
state machine transitions to the "Fail" state.
This MEP makes no claims about the disposition or handling of SOAP faults generated by the requesting SOAP node during any processing of the response message that follows the "Success" state in the requesting SOAP node's state transition table (see ???).
The One-way SOAP HTTP binding provides a binding of SOAP to HTTP. The binding conforms to the SOAP Protocol Binding Framework (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework) and supports the message exchange patterns and features described in ???.
The One-way SOAP HTTP binding is optional and SOAP nodes are NOT required to implement it. A SOAP node that correctly and completely implements the SOAP HTTP Request Binding may to be said to "conform to the WS-Addressing One-way SOAP HTTP Binding."
The WS-Addressing One-way SOAP HTTP binding defines a base URI according to the rules in HTTP/1.1 [RFC 2616]. I.e. the base URI is the HTTP Request-URI or the value of the HTTP Content-Location header field.
This binding of SOAP to HTTP is intended to make appropriate use of HTTP as an application protocol. For example, successful responses are sent with status code 200, and failures are indicated as 4XX or 5XX. This binding is not intended to fully exploit the features of HTTP, but rather to use HTTP specifically for the purpose of communicating with other SOAP nodes implementing the same binding. Therefore, this HTTP binding for SOAP does not specify the use and/or meaning of all possible HTTP methods, header fields and status responses. It specifies only those which are pertinent to the ??? or the ???, or which are likely to be introduced by HTTP mechanisms (such as proxies) acting between the SOAP nodes.
Certain optional features provided by this binding depend on capabilities provided by HTTP/1.1, for example content negotiation. Implementations SHOULD thus use HTTP/1.1 [RFC 2616] (or later compatible versions that share the same major version number). Implementations MAY also be deployed using HTTP/1.0, although in this case certain optional binding features may not be provided.
Note:
WS-Addressing One-way SOAP HTTP binding implementations need to account for the fact that HTTP/1.0 intermediaries (which may or may not also be SOAP intermediaries) may alter the representation of SOAP messages, even in situations where both the initial SOAP sender and ultimate SOAP receiver use HTTP/1.1.
Particularly when used with the ???, the HTTP messages
produced by this binding are likely to be
indistinguishable from those produced by non-SOAP implementations
performing similar operations.
Accordingly, some degree of interoperation can be made possible between SOAP nodes and other HTTP
implementations when using this binding.
For example, a conventional Web server (i.e. one not
written specifically to conform to this specification) might be used to respond
to SOAP-initiated HTTP GET's with representations of
Content-Type
"application/soap+xml".
Such interoperation is not a normative feature of this specification.
Even though HTTP often is used on the well-known TCP port 80, the use of HTTP is not limited to that port. As a result, it is possible to have a dedicated HTTP server for handling SOAP processing on a distinct TCP port. Alternatively, it is possible to use a separate virtual host for dealing with SOAP processing. Such configuration, however, is a matter of convenience and is not a requirement of this specification (see SOAP 1.2 Part 1 [SOAP Part 1]Binding to Application-Specific Protocols).
Conforming implementations of this binding:
MUST be capable of sending and receiving messages serialized using media type "application/soap+xml" whose proper use and parameters are described in ???.
MAY send requests and responses using other media types providing that such media types provide for at least the transfer of SOAP XML Infoset.
MAY, when sending requests, provide an HTTP Accept header field. This header field:
SHOULD indicate an ability to accept at minimum "application/soap+xml".
MAY additionally indicate willingness to accept other media types that satisfy 2 above.
This binding is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework):
"http://www.w3.org/2004/12/ws-addr/bindings/OnewayHTTP/"
An implementation of the WS-Addressing One-way SOAP HTTP binding MUST support at least ONE of the following message exchange patterns (MEPs):
An implementation of the WS-Addressing One-way SOAP HTTP binding MUST support the following features:
"http://www.w3.org/2003/05/soap/features/action/" (see ???)
For binding instances conforming to this specification:
A SOAP node instantiated at an HTTP client may assume the role (i.e. the
property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
) of
"RequestingSOAPNode".
A SOAP node instantiated at an HTTP server may assume the role (i.e.
the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
) of
"RespondingSOAPNode".
The remainder of this section describes the MEP state machine
and its relation to the HTTP protocol. In the state tables below,
the states are defined as values of the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State
(see ??? and ???), and are of type xs:anyURI
.
For brevity, relative URIs are used, the base URI being the value of http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
.
The message exchange pattern in use is not indicated in this binding. This information SHOULD be conveyed by a mechanism outside of this binding.
The overall flow of the behavior of a requesting SOAP node follows a state machine description consistent with either ??? or ??? (differences are indicated as necessary.) This binding supports streaming and, as a result, requesting SOAP nodes MUST avoid deadlock by accepting and if necessary processing binding-specific response information while the SOAP request is being transmitted (see 2.3 State Machine Description). The following subsections describe each state in detail.
In the "Init" state, a HTTP request is formulated according to ??? and transmission of the request is initiated.
Field | Value |
---|---|
HTTP Method | According to the http://www.w3.org/2003/05/soap/features/web-method/Method property. POST is the only value supported by this binding. |
Request URI | The value of the URI carried in the
http://www.w3.org/2003/05/soap/mep/ImmediateDestination property of the
message exchange context. |
Content-Type header field | The media type of the request entity body (if present) otherwise,
omitted (see ??? for a description of permissible media types).
If the SOAP envelope infoset in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property is null,
then the Content-Type header field MAY be omitted. |
action parameter | According to the value of the |
Accept header field (optional) | List of media types that are acceptable in response to the request message. |
Additional header fields | Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature. |
HTTP entity body | SOAP message serialized according to the rules for
carrying SOAP messages in the media type given by the
Content-Type header field. Rules for carrying SOAP messages in
media type "application/soap+xml" are given
in ???. If the SOAP envelope infoset in the
|
In the "Requesting" state, sending of the request continues while waiting for the start of the optional binding-specific response message. ??? details the transitions that take place when a requesting SOAP node receives an HTTP status line and response header fields. For some status codes there is a choice of possible next state. In cases where "Fail" is one of the choices, the next state is "Fail".
Status Code | Reason phrase | Significance/Action | NextState |
---|---|---|---|
2xx | Successful | ||
200 | OK | "Sending+Receiving" or "Success" | |
3xx | Redirection | The requested resource has
moved and the HTTP request SHOULD be retried using the URI carried in the
associated Location header field as the new value for the
| "Init" |
4xx | Client Error | ||
400 | Bad Request | Indicates a problem with the received HTTP request message. | "Sending+Receiving" or "Fail" |
401 | Unauthorized | Indicates that the HTTP request requires authorization. If the simple authentication feature is unavailable or the operation of simple authentication ultimately fails, then the message exchange is regarded as having completed unsuccessfully. | "Requesting" or "Fail" |
405 | Method not allowed | Indicates that the peer HTTP server does not support the requested HTTP method at the given request URI. The message exchange is regarded as having completed unsuccessfully. | "Fail" |
415 | Unsupported Media Type | Indicates that the peer HTTP server does not support the Content-type used to encode the request message. The message exchange is regarded as having completed unsuccessfully. | "Fail" |
5xx | Server Error | ||
500 | Internal Server Error | Indicates a server problem or a problem with the received request | "Sending+Receiving" or "Fail" |
??? refers to some but not all of the existing HTTP/1.1 [RFC 2616] status codes. In addition to these status codes, HTTP provides an open-ended mechanism for supporting status codes defined by HTTP extensions (see RFC 2817 [RFC 2817] for a registration mechanism for new status codes). HTTP status codes are divided into status code classes as described in HTTP [RFC 2616], section 6.1.1. The WS-Addressing One-way SOAP HTTP binding follows the rules of any HTTP application which means that an implementation of the WS-Addressing One-way SOAP HTTP binding must understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response must not be cached.
Note:
There may be elements in the HTTP infrastructure configured to modify HTTP response entity bodies for 4xx and 5xx status code responses. For example, some HTTP origin servers have such a feature as a configuration option. This behavior may interfere with the use of 4xx and 5xx status code responses carrying SOAP fault messages in HTTP and it is recommended that such behavior is disabled for resources accepting SOAP/HTTP requests. If the rewriting behavior cannot be disabled, SOAP/HTTP cannot be used in such configurations.
In the "Sending+Receiving" state (??? only), the transmission of the request message and receiving of the response message is completed. This response message is assumed to contain an empty body. This response message may contain a SOAP envelope serialized according to the rules for carrying SOAP messages in the media type given in the Content-Type header field. Such usage is considered non-normative, and accordingly is not modelled in the state machine.
The response MAY be of content type other than "application/soap+xml". Such usage is considered non-normative, and accordingly is not modeled in the state machine. Interpretation of such responses is at the discretion of the receiver.
The overall flow of the behavior of a responding SOAP node follows a state machine description consistent with either ??? or ??? (differences are indicated as necessary). The following subsections describe each state in detail.
In the "Init" state, the binding waits for the start of an inbound request message. ??? describes the errors that a responding SOAP node might generate while in the "Init" state. In this state no SOAP message has been received, therefore the SOAP node cannot generate a SOAP fault.
Problem with Message | HTTP Status Code | HTTP Reason Phrase (informative) |
---|---|---|
Malformed Request Message | 400 | Bad request |
HTTP Method is not POST | 405 | Method Not Allowed |
Unsupported message encapsulation method | 415 | Unsupported Media |
In the "Receiving" state, the binding receives the request and any associated message and waits for the start of a response message to be available. ??? describes the HTTP response header fields generated by the responding SOAP node. ??? describes the HTTP status codes that can be generated by the responding SOAP node.
Field | Value |
---|---|
Status line | 200, or set according to ??? if a SOAP fault was generated. |
Content-Type header field | The media type of the response body, see ??? for a description of permissible media types. |
Additional header fields | Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature. |
HTTP Entity Body | Assume to be empty. It MAY contain a SOAP message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header field. Rules for carrying SOAP messages in "application/soap+xml" are given in ???. |
SOAP Fault | HTTP Status Code | HTTP Reason Phrase (informative) |
---|---|---|
env:VersionMismatch | 500 | Internal server error |
env:MustUnderstand | 500 | Internal server error |
env:Sender | 400 | Bad request |
env:Receiver | 500 | Internal server error |
env:DataEncodingUnknown | 500 | Internal server error |
The One-way SOAP HTTP Binding (see ???) can be considered as an extension of the HTTP application protocol. As such, all of the security considerations identified and described in section 15 of the HTTP specification [RFC 2616] apply to the WS-Addressing One-way SOAP HTTP binding in addition to those described in SOAP 1.2 Part 1 [SOAP Part 1]Security Considerations. Implementors of the WS-Addressing One-way SOAP HTTP binding should carefully review this material.