SCDJWS Study Guide: SOAP
Using SOAP in HTTP
SOAP defines a binding to the HTTP protocol. Binding SOAP to HTTP provides the advantage of being able to use the formalism and decentralized flexibility of SOAP with the rich feature set of HTPP. Carrying SOAP in HTTP does not mean that SOAP overrides existing semantics of HTTP but rather that the semantics of SOAP over HTTP maps naturally to HTTP semantics.
SOAP naturally follows the HTTP request/response message model providing SOAP request parameters in a HTTP request and SOAP response parameters in a HTTP response. Note, however, that SOAP intermediaries are NOT the same as HTTP intermediaries. That is, an HTTP intermediary addressed with the HTTP Connection header field cannot be expected to inspect or process the SOAP entity body carried in the HTTP request.
HTTP applications MUST use the media type "text/xml" according to RFC 2376 when including SOAP entity bodies in HTTP messages.
This binding describes the relationship between parts of the SOAP request message and various HTTP headers. All SOAP requests use the HTTP POST method and specify at least three HTTP headers: Content-Type, Content-Length, and a custom header SOAPAction. The actual SOAP message is passed as the body of the request or response.
The SOAPAction header indicates to the HTTP server that the request is a SOAP request. The value of the header is a URI. Beyond that, its value is undefined.
The Content-Length header for SOAP requests and responses is set to the number of bytes in the body of the request or response.
An example SOAPAction header in an HTTP request. The string preceding the # is the namespace name of the first child of the Body element whereas the string following the # is the local name of that element.
POST /endpoint.pl HTTP/1.1
Content-Type: text/xml; charset=UTF-16
<m:Method xmlns:m='urn:example-org:demos' />
SOAP 1.1 defines a single protocol binding, for HTTP. The WS-I Basic Profile 1.0 mandates the use of that binding, and places the following constraints on it use:
- HTTP Versions
Several versions of HTTP are defined. HTTP/1.1 has performance advantages, and is more clearly specified than HTTP/1.0.
|R1140||A MESSAGE SHOULD be sent using HTTP/1.1.|
|R1141||A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.|
Note that support for HTTP/1.0 is implied in HTTP/1.1, and that intermediaries may change the version of a message; for more information about HTTP versioning, see RFC2145, "Use and Interpretation of HTTP Version Numbers."
- Identifying SOAP Fault
Some consumer implementations use
only the HTTP status code to determine the presence of a SOAP
Fault. Because there are situations where the Web infrastructure
changes the HTTP status code, and for general reliability, the Profile
requires that they examine the envelope.
|R1107||A RECEIVER MUST interpret SOAP messages containing only a soap:Fault element as a Fault.|
- HTTP Methods and Extensions
specification defined its HTTP binding such that two possible methods
could be used, the HTTP POST method and the HTTP Extension Framework's
M-POST method. The Profile requires that only the HTTP POST method be
used and precludes use of the HTTP Extension Framework.
|R1132||A HTTP request MESSAGE MUST use the HTTP POST method.|
|R1108||A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).|
The HTTP Extension Framework is an experimental mechanism for extending HTTP in a modular fashion. Because it is not deployed widely and also because its benefits to the use of SOAP are questionable, the Profile does not allow its use.
- SOAPAction Header Syntax
Testing has demonstrated that requiring the SOAPAction HTTP header field-value to be quoted increases interoperability of implementations. Even though HTTP allows unquoted header field-values, some SOAP implementations require that they be quoted.
SOAPAction is purely a hint
processors. All vital information regarding the intent of a message is
carried in soap:Envelope.
|R1109||The value of the SOAPAction HTTP header field in a HTTP request MESSAGE MUST be a quoted string.|
|R1119||A RECEIVER MAY respond with a Fault if the value of the SOAPAction HTTP header field is not quoted.|
A WSDL Description that has:
<soapbind:operation soapAction="foo" />
results in a message with a SOAPAction HTTP header field of:
A WSDL Description that has:
<soapbind:operation soapAction="" />
results in a message with a corresponding SOAPAction HTTP header field as follows:
- HTTP and TCP Ports
SOAP is designed to take advantage of the HTTP
infrastructure. However, there are some situations (e.g., involving
proxies, firewalls and other intermediaries) where there may be harmful
side effects. As a result, instances may find it advisable to use ports
other than the default for HTTP (port 80).
||An INSTANCE MAY accept connections on TCP port 80 (HTTP).|
There has been considerable debate within the W3C and IETF regarding the propriety of the use of port 80 for SOAP messages bound to HTTP. It has been concluded that this is an acceptable practice.
- HTTP Success Status Codes
HTTP uses the 2xx series of status
codes to communicate success. In particular, 200 is the default for
successful messages, but 202 can be used to indicate that a message has
been submitted for processing. Additionally, other 2xx status codes may
be appropriate, depending on the nature of the HTTP interaction.
An INSTANCE MUST use a 2xx HTTP status code for responses that indicate a successful outcome of a request.
||An INSTANCE SHOULD use a "200 OK" HTTP status code for responses that contain a SOAP message that is not a SOAP fault.|
||An INSTANCE SHOULD use either a "200 OK" or "202 Accepted" HTTP status code for a response that does do not contain a SOAP message but indicates successful HTTP outcome of a request.|
- HTTP Redirect Status Codes
There are interoperability problems
with using many of the HTTP redirect status codes, generally
surrounding whether to use the original method, or GET.
The Profile mandates "307 Temporary Redirect", which has the semantic
of redirection with the same HTTP method, as the correct status code
for redirection. For more information, see the 3xx status code
descriptions in RFC2616.
||An INSTANCE MUST use HTTP status code "307 Temporary Redirect" when redirecting a request to a different endpoint.|
||A CONSUMER MAY automatically redirect a request when it encounters a "307 Temporary Redirect" HTTP status code in a response.|
RFC2616 notes that user-agents should not automatically redirect requests; however, this requirement was aimed at browsers, not automated processes (which many Web services will be). Therefore, the Profile allows, but does not require, consumers to automatically follow redirections.
- HTTP Client Error Status Codes
HTTP uses the 4xx series of status
codes to indicate failure due to a client error. Although there are a
number of situations that may result in one of these codes, the Profile
highlights those when the payload of the HTTP request is not the proper
media type (i.e., "text/xml", as required by the SOAP/HTTP
binding), and when the anticipated method ("POST") is not used.
||An INSTANCE MUST use a 4xx HTTP status code for responses that indicate a problem with the format of the request.|
||An INSTANCE SHOULD use a "400 Bad Request "HTTP status code, if the request message is a malformed HTTP request, or not well-formed XML.|
||An INSTANCE SHOULD use a "405 Method not Allowed" HTTP status code if the request method was not "POST".|
||An INSTANCE SHOULD use a "415 Unsupported Media Type" HTTP status code if the Content-Type HTTP request header did not have a value consistent with the value specified for the corresponding binding of the input message.|
Note that these requirements do not force an instance to respond to requests. In some cases, such as Denial of Service attacks, an instance may choose to ignore requests.
- HTTP Server Error Status Codes
HTTP uses the 5xx series of status
codes to indicate failure due to a server error.
||An INSTANCE MUST use a "500 Internal Server Error" HTTP status code if the response message is a SOAP Fault.|
- HTTP Cookies
State Management Mechanism ("Cookies") allows the
creation of stateful sessions between Web browsers and servers. Being
designed for hypertext browsing, Cookies do not have well-defined
semantics for Web services, and, because they are external to the SOAP
Envelope, are not accommodated by either SOAP
1.1 or WSDL 1.1. However, there are situations where it may be
reasons, the Profile limits the ways in which Cookies can be used,
without completely disallowing them.
||An INSTANCE MAY use the HTTP state mechanism ("Cookies").|
||An INSTANCE using Cookies SHOULD conform to RFC2965.|
||An INSTANCE SHOULD NOT require consumer support for Cookies in order to function correctly.|
||The value of the cookie MUST be considered to be opaque by the CONSUMER.|
The Profile recommends that cookies not be required by instances for proper operation; they should be a hint, to be used for optimization, without materially affecting the execution of the Web service. However, they may be required in legacy integration and other exceptional use cases, so requiring them does not make an instance non-conformant. While Cookies thus may have meaning to the instance, they should not be used as an out-of-bound data channel between the instance and the consumer. Therefore, interpretation of Cookies is not allowed at all by the consumer - it is required to treat them as opaque (i.e., have no meaning to the consumer).