SCDJWS Study Guide: SOAP

Printer-friendly version | Mail this to a friend

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.

SOAPAction	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.
Content-Type	Content-Type: text/xml; charset=<character encoding> The Content-Type header for SOAP requests and responses specifies the MIME type for the message and is always text/xml. It may also specify the character encoding used for the XML body of the HTTP request or response. This follows the text/xml part of the header values.
Content-Length	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
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.

	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

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.

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

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

R1110

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.

	R1124	An INSTANCE MUST use a 2xx HTTP status code for responses that indicate a successful outcome of a request.
	R1111	An INSTANCE SHOULD use a "200 OK" HTTP status code for responses that contain a SOAP message that is not a SOAP fault.
	R1112	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.

	R1130	An INSTANCE MUST use HTTP status code "307 Temporary Redirect" when redirecting a request to a different endpoint.
	R1131	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.

	R1125	An INSTANCE MUST use a 4xx HTTP status code for responses that indicate a problem with the format of the request.
	R1113	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.
	R1114	An INSTANCE SHOULD use a "405 Method not Allowed" HTTP status code if the request method was not "POST".
	R1115	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.

R1126

An INSTANCE MUST use a "500 Internal Server Error" HTTP status code if the response message is a SOAP Fault.

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.

	R1120	An INSTANCE MAY use the HTTP state mechanism ("Cookies").
	R1122	An INSTANCE using Cookies SHOULD conform to RFC2965.
	R1121	An INSTANCE SHOULD NOT require consumer support for Cookies in order to function correctly.
	R1123	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).