Editors' Copy: SOAP Version 1.2

6. Default binding of SOAP onto HTTP

This section defines a default binding of the SOAP protocol to the HTTP 1.1 [5] application protocol. Alternate bindings of the SOAP protocol onto HTTP or other transfer/transport protocols MAY be defined external to this specification. An example of an alternate binding onto the HTTP application protocol might be to leverage the HTTP GET method to be used to allow a SOAP client to "poll" a SOAP server for messages.

Binding SOAP to HTTP provides the advantages of 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 SOAP over HTTP inherits HTTP semantics.

This default binding of SOAP onto HTTP SHALL be identified by the URI:

http://www.w3.org/2001/06/soap/http-default-binding

SOAP servers that support this default binding to HTTP SHOULD [SHALL?] use this URI in any advertisement of the service transport binding endpoint, such as defined in [WSDL].

Note: 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.

6.1 Message Exchange Patterns Supported

[should there be a definititive enumeration of the recognized MEPs somewhere in this specification?]

The Message Exchange Patterns (MEP) supported by this default binding are one-way and request/response.

Using SOAP for RPC, as defined in section 7, naturally follows the HTTP request/response MEP by providing a SOAP request message in the HTTP POST request message as defined in section 6.2 and a SOAP response message in the HTTP response as defined in section 6.3.

Using SOAP for one-way message exchanges is achieved by the client sending a SOAP one-way message in the body of the HTTP POST message as defined in section 6.2 with the SOAP HTTP server returning an HTTP response with a 204 status and an empty response entity body.

6.2 SOAP HTTP Request

Although SOAP might be used in combination with a variety of HTTP request methods, this default binding only defines sending a SOAP message from HTTP client to the origin server using the HTTP POST operation.

6.2.1 Content-Type Header

The Content-Type header identifies the encapsulation mechanism used to convey the SOAP envelope in the entity body of the HTTP request message. The default encapsulation mechanism is none, in which case the Content-Type header of the HTTP request SHALL be "text/xml" as defined in RFC 2376 [3]. [See note below regarding media type.]

A SOAP HTTP application conforming to this default binding MUST support the default encapsulation mechanism of none.

Other encapsulation mechanisms MAY be supported by a SOAP HTTP application conforming to this default binding such as those described in the SOAP Messages with Attachments specification[14] or DIME[15] specifications.

A SOAP HTTP server receiving a SOAP HTTP request message that has used an encapsulation mechanism that it does not support/understand SHALL respond with an HTTP status code of 415 Unsupported Media Type.

This specification does not define how a SOAP HTTP client determines what encapsulation mechanisms are supported by a given SOAP HTTP server.

6.2.1 HTTP Content-Length Header

A SOAP HTTP request message SHOULD include the Content-Length header as defined in RFC2616.

6.2.2 HTTP Accept Headers

A SOAP request message sent via the HTTP POST operation as defined for this binding SHOULD contain the HTTP Accept header indicating the list of MIME media types of encapsulation mechanisms supported by the client sending the request message. A SOAP HTTP request message that does not contain the Accept HTTP header SHALL be treated by a SOAP HTTP server process as being equivalent to having an Accept HTTP header with the value "text/xml".

e.g.

Accept: text/xml, multipart/related, application/dime

[note that a specific MIME media type for a SOAP envelope would allow for
a client to be precise regarding what it expects in response.
e.g.
Accept: application/soap+xml, multipart/related; type=application/soap+xml,
application/dime; type=application/soap+xml
This leaves no doubt on the part of the SOAP processor as to what the
requesting client's capabilities are.]

A SOAP HTTP server SHOULD also observe the semantics of the Accept-Charset, Accept-Encoding and Accept-Language HTTP request headers in processing the response SOAP message as defined in sections 14.2, 14.3 and 14.4 of RFC2616.

6.2.3 The SOAPAction HTTP Header Field

The SOAPAction HTTP request header defined in the SOAP1.1 specification has been deprecated. An HTTP client SHOULD NOT use this header field when issuing a SOAP HTTP Request. An HTTP SOAP server MUST NOT reject a request that does not include the SOAPAction header. [NOTE: I realize that we haven't come to consensus on any decision as to what to do about SOAPAction. This text reflects option "B" which is my preference. If we are to refine the specification of SOAPAction such that its use, purpose and intent are more clearly described, that work needs to be done soon!].

6.2.4 Extension Entity Headers

A SOAP HTTP request message MAY include extension entity headers as defined in RFC2616. However, these fields cannot be assumed to be recognizable by the recipient. A SOAP HTTP server process MAY ignore unrecognized extension entity headers included in a SOAP HTTP request message. A SOAP HTTP server process conformant to this default binding MUST NOT require that a SOAP HTTP request message contain specific extension entity headers.

6.3 SOAP HTTP Response

SOAP over HTTP as defined for this default binding follows the semantics of the HTTP Status codes for communicating status information in HTTP.

6.3.1 HTTP 2xx Successful

A 2xx status code indicates that the request, including the SOAP message component, was successfully received, understood, and accepted by the receiving SOAP processor.

A 200 OK status SHALL be used to communicate that a SOAP message is being conveyed within the entity body of the HTTP response. The response SOAP message SHALL be implicitly correlated with the request SOAP message sent in the HTTP POST operation.
A 202 Accepted status MAY be returned by the server to indicate that the request SOAP message has been received, but has not been processed.
A 204 No Content status SHALL be used to communicate that the SOAP message has been successfully processed by the SOAP application. As stipulated in [5], the 204 response MUST NOT include a message body.
HTTP status codes 201 Created, 203 Non-Authoritive Information, 205 Reset Content and 206 Partial Content SHOULD NOT be returned by a SOAP processor conforming to this default binding.

6.3.2 HTTP 3xx Redirection

No SOAP specific behavior is associated with the 3xx status codes. A SOAP client
SHOULD be prepared to receive and process a 3xx status code as defined in RFC2616
section 10.3.

6.3.3 HTTP 4xx Client Error

In general, a SOAP HTTP client SHOULD be prepared to handle any of the 4xx class of HTTP status codes. However, the following status codes have specific meaning within the context of this SOAP binding to HTTP.

A 400 Bad Request status SHALL be returned in the event that the SOAP message contained within the body of an HTTP request message is not well formed XML or in the case where a SOAP envelope was expected in the body of the HTTP POST request and none was present.
A 405 Method Not Allowed status SHALL be returned in the event that the method specified in the HTTP request is not POST. As specified in RFC2616, the HTTP response MUST include an Accept header that includes at least POST.
A 415 Unsupported Media Type status code SHALL be returned in the event that the encapsulation mechanism used for the SOAP message in the HTTP request is unsupported by the server.

6.3.4 HTTP 5xx Server Error

If an error occurs while processing a SOAP HTTP message, 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 (see section 4.4) indicating the SOAP processing error. [I'm still not convinced that this is appropriate for SOAP Faults, related issue is Issue 12]

6.5 SOAP HTTP Examples

Example 43

POST /StockQuote HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

SOAP HTTP Request Using POST

Example 44

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
 . . .
</env:Envelope>

SOAP HTTP Response to Example 43

8. Security Considerations

Not described in this document are methods for integrity and privacy protection. Such issues will be addressed more fully in a future version(s) of this document. [NOTE: at the very least, some reference to the security considerations section in RFC2616 as relates to the default HTTP binding should be made].

9. References

[1] S. Bradner, "The Internet Standards Process -- Revision 3", RFC2026, Harvard University, October 1996

[2] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997

[3] E. Whitehead, M. Murata, "XML Media Types", RFC2376, UC Irvine, Fuji Xerox Info. Systems, July 1998

[4] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998.

[5] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, January 1997

[6] H. Nielsen, P. Leach, S. Lawrence, "An HTTP Extension Framework", RFC 2774, Microsoft, Microsoft, Agranat Systems

[7] W3C Recommendation "The XML Specification"

[8] W3C Recommendation "Namespaces in XML"

[9] W3C Proposed Recommendation "XML Linking Language"

[10] W3C Recommendation "XML Schema Part 1: Structures"

[11] W3C Recommendation "XML Schema Part 2: Datatypes"

[12] Transfer Syntax NDR, in "DCE 1.1: Remote Procedure Call"

[13] N. Freed, N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC2045, Innosoft, First Virtual, November 1996

[14] W3C Note SOAP Messages with Attachments

[15] Henrik Frystyk Nielsen, Henry Sanders, Erik Christensen, "Direct Internet Message Encapsulation", May 2001

A. SOAP Envelope Examples

A.1 Sample Encoding of Call Requests

Example 47

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope
  xmlns:env="http://www.w3.org/2001/06/soap-envelope"
  env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" >
   <env:Header>
       <t:Transaction
           xmlns:t="http://example.org/2001/06/tx"
           env:mustUnderstand="1" >
               5
       </t:Transaction>
   </env:Header>
   <env:Body>
       <m:GetLastTradePrice xmlns:m="http://example.org/2001/06/quotes" >
           <m:symbol>DEF</m:symbol>
       </m:GetLastTradePrice>
   </env:Body>
</env:Envelope>

Similar to Example 1 but with a Mandatory Header

Example 48

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"
              env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" >
   <env:Body>
       <m:GetLastTradePriceDetailed xmlns:m="http://example.org/2001/06/quotes" >
           <Symbol>DEF</Symbol>
           <Company>DEF Corp</Company>
           <Price>34.1</Price>
       </m:GetLastTradePriceDetailed>
   </env:Body>
</env:Envelope>

Similar to Example 1 but with multiple request parameters

A.2 Sample Encoding of Response

Example 49

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"
              env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" >
   <env:Header>
       <t:Transaction xmlns:t="http://example.org/2001/06/tx"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xmlns:xs="http://www.w3.org/2001/XMLSchema"
                      xsi:type="xs:int" env:mustUnderstand="1" >
           5
       </t:Transaction>
   </env:Header>
   <env:Body>
       <m:GetLastTradePriceResponse xmlns:m="http://example.org/2001/06/quotes">
           <Price>34.5</Price>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>

Similar to Example 2 but with a Mandatory Header

Example 50

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"
              env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" >
   <env:Body>
       <m:GetLastTradePriceResponse xmlns:m="http://example.org/2001/06/quotes" >
           <PriceAndVolume>
               <LastTradePrice>34.5</LastTradePrice>
               <DayVolume>10000</DayVolume>
           </PriceAndVolume>
       </m:GetLastTradePriceResponse>
   </env:Body>
</env:Envelope>

Similar to Example 2 but with a Struct

Example 51

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope">
   <env:Body>
       <env:Fault>
           <faultcode>env:MustUnderstand</faultcode>
           <faultstring>SOAP Must Understand Error</faultstring>
       </env:Fault>
   </env:Body>
</env:Envelope>

Similar to Example 2 but Failing to honor Mandatory Header

Example 52

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" >
  <env:Body>
    <env:Fault>
      <faultcode>env:Server</faultcode>
      <faultstring>Server Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://example.org/2001/06/faults" >
          <message>My application didn't work</message>
          <errorcode>1001</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

Similar to Example 2 but Failing to handle Body