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.

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
Content-Length: 167
SOAPAction: urn:example-org:demos#Method

<s:Envelope
    xmlns:s='http://schemas.xmlsoap.org/soap/envelope/' >
  <s:Body>
    <m:Method xmlns:m='urn:example-org:demos' />
  </s:Body>
</s:Envelope>

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.

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.

• HTTP Methods and Extensions

The SOAP1.1 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.

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 to processors. All vital information regarding the intent of a message is carried in soap:Envelope.

For example,

CORRECT:
A WSDL Description that has:
<soapbind:operation soapAction="foo" />
results in a message with a SOAPAction HTTP header field of:
SOAPAction: "foo"

CORRECT:
A WSDL Description that has:
<soapbind:operation />
or
<soapbind:operation soapAction="" />
results in a message with a corresponding SOAPAction HTTP header field as follows:
SOAPAction: ""

• 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).

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.

• 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.

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.

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.

• HTTP Cookies

The HTTP 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 necessary to use Cookies; e.g., for load balancing between servers, or for integration with legacy systems that use Cookies. For these reasons, the Profile limits the ways in which Cookies can be used, without completely disallowing them.

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).