6 Using SOAP in HTTP

[Previous] [Next]

This section describes how to use SOAP within HTTP with or without using the HTTP Extension Framework. 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 HTTP. 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 [3] when including SOAP entity bodies in HTTP messages.

6.1 SOAP HTTP Request

Although SOAP might be used in combination with a variety of HTTP request methods, this binding only defines SOAP within HTTP POST requests (see section 7 for how to use SOAP for RPC and section 6.3 for how to use the HTTP Extension Framework).

6.1.1 The SOAPAction HTTP Header Field

The SOAPAction HTTP request header field can be used to indicate the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client MUST use this header field when issuing a SOAP HTTP Request.

 soapaction = "SOAPAction" ":" [ <"> URI-reference <"> ] URI-reference = <as defined in RFC 2396 [4]> 

The presence and content of the SOAPAction header field can be used by servers such as firewalls to appropriately filter SOAP request messages in HTTP. The header field value of empty string ("") means that the intent of the SOAP message is provided by the HTTP Request-URI. No value means that there is no indication of the intent of the message.

Examples:

 SOAPAction: "http://electrocommerce.org/abc#MyMessage" SOAPAction: "myapp.sdl" SOAPAction: "" SOAPAction: 

6.2 SOAP HTTP Response

SOAP HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc.

In case of a SOAP error while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP Fault element (see section 4.4) indicating the SOAP processing error.

6.3 The HTTP Extension Framework

A SOAP message MAY be used together with the HTTP Extension Framework [6] in order to identify the presence and intent of a SOAP HTTP request.

Whether to use the Extension Framework or plain HTTP is a question of policy and capability of the communicating parties. Clients can force the use of the HTTP Extension Framework by using a mandatory extension declaration and the "M-" HTTP method name prefix. Servers can force the use of the HTTP Extension Framework by using the 510 "Not Extended" HTTP status code. That is, using one extra round trip, either party can detect the policy of the other party and act accordingly.

The extension identifier used to identify SOAP using the Extension Framework is http://schemas.xmlsoap.org/soap/envelope/.

6.4 SOAP HTTP Examples

Example 3

SOAP HTTP Using POST

 POST /StockQuote HTTP/1.1 Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://electrocommerce.org/abc#MyMessage" <SOAP-ENV:Envelope... HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <SOAP-ENV:Envelope... 

Example 4

SOAP Using HTTP Extension Framework

 M-POST /StockQuote HTTP/1.1 Man: "http://schemas.xmlsoap.org/soap/envelope/"; ns=NNNN Content-Type: text/xml; charset="utf-8" Content-Length: nnnn NNNN-SOAPAction: "http://electrocommerce.org/abc#MyMessage" <SOAP-ENV:Envelope... HTTP/1.1 200 OK Ext: Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <SOAP-ENV:Envelope...