The SOAP HTTP Binding provides a
binding of SOAP to HTTP.
The 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 Binding may to be said to "conform to
the SOAP 1.2 HTTP Binding."
The SOAP version 1.2
specification does not preclude development of other bindings to HTTP or
bindings to other protocols, but communication with nodes using such other
bindings is not a goal.
The 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.
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:
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.
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:
1. MUST be capable of sending and receiving
messages serialized using media type "application/soap+xml" whose
proper use and parameters are described in A. The
application/soap+xml Media Type.
2. MAY send requests and responses using
other media types providing that such media types provide for at least the
transfer of SOAP XML Infoset.
3. MAY, when sending requests, provide an
HTTP Accept header field. This header field:
o
SHOULD indicate
an ability to accept at minimum "application/soap+xml".
o
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/2003/05/soap/bindings/HTTP/"
The overall flow of the behavior
of a requesting SOAP node follows that of a HTTP requestor (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 SOAP response information while the SOAP request is being
transmitted.
A HTTP request is formulated
according to Table 16.
|
Field |
Value |
|
HTTP Method |
POST and GET are the only values supported by this binding. POST MUST be used is the request is to carry a SOAP message, GET SHOULD be used if the request does not carry a SOAP message and is safe (as per HTTP definition of safe). |
|
Request URI |
The address of the endpoint to which the request will be made. |
|
Content-Type header field |
The media type of
the request entity body (if present) otherwise, omitted (see 7.1 Introduction for a description of
permissible media types). If there is no SOAP envelope infoset in the request,
then the |
|
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 A. The application/soap+xml Media Type. If there
is no SOAP envelope infoset in the request, the entity body is omitted |
Table
17 details the HTTP response codes and their meaning for the SOAP
binding.
|
Reason phrase |
Significance/Action |
|
|
2xx |
Successful |
|
|
200 |
OK |
The response message follows in HTTP response entity body. |
|
202 |
Accepted |
The request message was accepted, no response was received. |
|
3xx |
Redirection |
The requested resource has moved and the HTTP request SHOULD be retried
using the URI carried in the associated Location header field. |
|
303 |
See Other |
The response can be retrieved using a HTTP GET from the URI in the
supplied Location header. |
|
4xx |
Client Error |
|
|
400 |
Bad Request |
Indicates a problem with the received HTTP request message. |
|
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. |
|
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. |
|
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. |
|
5xx |
Server Error |
|
|
500 |
Internal Server Error |
Indicates a server problem or a problem with the received request |
Table
17 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 SOAP HTTP binding follows the rules of any HTTP application
which means that an implementation of the 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.
The overall flow of the behavior
of a responding SOAP node follows that for a HTTP server.
Table
18 describes the errors that a responding SOAP node might generate due
to HTTP level problems.
|
Problem with Message |
HTTP Status Code |
HTTP Reason Phrase (informative) |
|
Malformed Request Message |
400 |
Bad request |
|
HTTP Method is neither POST nor GET |
405 |
Method Not Allowed |
|
Unsupported message encapsulation method |
415 |
Unsupported Media |
Table
19 describes the HTTP response header fields generated by the
responding SOAP node. Table 20
describes the HTTP status codes associated with SOAP faults that can be
generated by the responding SOAP node.
|
Field |
Value |
|
Status line |
200, or set according to Table 20
if a SOAP fault was generated. |
|
Content-Type header field |
The media type of the response body, see 7.1 Introduction 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 |
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 A. The application/soap+xml Media Type. |
|
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 SOAP HTTP Binding (see 7. SOAP HTTP Binding) 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 SOAP HTTP Binding in addition to
those described in SOAP 1.2 Part 1 [SOAP Part 1] Security
Considerations. Implementors of the SOAP HTTP Binding should carefully
review this material.