SOAP HTTP GET Binding Version 0.1

1 Introduction

For a variety of reasons, it is desirable that some web services, compliant with the SOAP HTTP Binding, can also be accessed via HTTP GET. This requirement mandates that the information necessary to access the resource can be expressed in an HTTUP URI The purpose of this document is to set forth a minimal set of requirements, to introduce a model and corresponding syntax for creating URIs responsive to HTTP GET. The main audience is Web Service authors who have need of expressing Web Services in HTTP GET URIspace.

1.1 Requirements

Simple RPC style SOAP requests can be encoded in a URL format. The subset of SOAP Messages are:
- BODY only
- Document or RPC Encoded requests where the BODY contains only one Child, aka a method
- requests where the method contains only children. That is, structured parameters are excluded
- URI length should be short.
The mapping from SOAP HTTP POST Binding to HTTP GET and back shall be automatable.
An HTTP Node shall not need to differentiate between SOAP-ness and non-soapness.

1.2 Out-of-scope

There are many possible requirements towards a more full encoding of SOAP in URL. Some of them are:

HTTP FORM POST binding
Structured content
SOAP Headers
Multiple Namespaces
XML Base
HTTP PUT, DELETE binding support
Alternative POST bindings
Attributes
xsi:type declarations

2 Overview

Using the oft-quote stock quote example, it is a simple matter to convert the XML structure into a URL-encoded structure. From the SOAP 1.2 usage scenarios document,

<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
   <env:Body>
     <r:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
             xmlns:r="http://example.org/2001/06/quotes">
       <r:Symbol>DEF</r:Symbol>
     </r:GetLastTradePrice>
   </env:Body>
 </env:Envelope>

This message is sent via the SOAP HTTP POST binding to a URI, such as http://www.example.org/stockService

A sample mapping of how this would like in URI space is (remember the "/" isn't escaped for illustrative purposes):

http://example.org/stockService/LastTradingPrice&
xmlnsuri=/2001/06/quotes&xmlns=r&encodingStyle=http://www.w3.org/2001/12/soap-encoding&Symbole=DEF

3 Processing Model

3.1 SOAP HTTP POST to HTTP URI:

The rules for the mapping are:

The SOAP Bodys first child element name prefix and postPrefix are extracted. Prefixes that are allowed are only get
Assuming the prefix is get, case-insensitive, the postPrefix preceeded by a "/" are appended to the URL
The namespace name is escaped and converted into the value of the xmlnsuri parameter. If the scheme and domain name of the URI is the same as the schema/domain of the xmlnsuri, then the scheme and domain name may be omitted
The namespace prefex is converted into the value of the xmlns parameter.
An encoding style attribute is converted into an encodingStyle parameter
each of the children of the SOAP Body child element are escaped and converted into element=value parameters

For a node to map the GET request into a SOAP HTTP POST request, it follows the reverse order:

3.2 HTTP URI to SOAP HTTP POST

An HTTP Node that is configured to map HTTP GETs into URIs SHOULD convert requests into SOAP HTTP POSTs:

Create a SOAP envelope with an empty body element. The namespace prefix is "env"
Create the body element name by concatenating "Get" with the last item in the URI path element
Give the body element the correct prefix from the xmlns parameter
Create an xmlns: attribute from the xmlns parameter and the unescaped xmlnsuri parameter. If the xmlns attribute is a relative URI, that is it does not contain a scheme and domain name, then the scheme/domain name of the URI is prepended to the xmlns value.
Create an encodingStyle attribute if one exists in the parameter list
Create elements for each of the subsequent parameters. The element Name is the parameter name, and the element content is the parameter value after unescaping is peformed.

3.3 Limitations

There are variety of limitations when URL encoding SOAP requests

URI Length. There are various documented and undocumented limits to URLs. A reasonable limit appears to be 4K. There are many reasons why URL length limits could be reached.
Internationalization. The use of I18N characters presents difficulties for encoding the character set information
Security/Privacy. As URLs are stored in various locations - proxies, caches, browser history, monitoring software - there exists privacy and security concerns about the use of URIs.

4 Appendix

4.1 Issues List

4.2 Discussion of out-of-scope requirements

This is section is to show possible solutions to the out-of-scope requirements. It is only here to prove that there are possible solutions.

4.2.1 Structured content

It possible to convert a subset of XML syntax into URI space. One mechanism to do this is to embed the relative XPath expression in the URI parameter name. this requires escaping the "/". For illustrative purposes, the "/" has not been escaped. For example

<parent><child/></parent>

could be encoded as

 &parent=&./child=

Another example has multiple children

<parent><child>a</child><child>b</child></parent><parent><child>c</child></parent>

could be encoded as

 &parent=&./child=a&child=b&../parent=&./child=c

4.2.2 SOAP Headers

The oft-quoted stock quote example regularly has a simple HTTP Header associated with it

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

A sample mapping of how this would like in URI space is:

http://example.org/stockService/LastTradingPrice&Header=&xmlnsuri=/2001/06/tx&xmlns=t&Transaction=5&../../Body=&
xmlnsuri=/2001/06/quotes&xmlns=r&encodingStyle=http://www.w3.org/2001/12/soap-encoding&Symbole=DEF

This still doesnt allow multiple namespaced elements or attributes, such as env:mustUnderstand="1".

4.2.3 Mixed namespaces

It is possible to escape the ":" namespace separator, so elements could contain namespace decls.

4.2.4 Attributes

This does not specify how a child is known to be an element or attribute. One solution would be to require that any child element node used "./" in the parameter, and the absence of such indicated an attribute.

4.2.5 Other HTTP Methods

There are a variety of other HTTP methods and common method prefixes that could be mapped. For example, a setStockPrice SOAP Method could be mapped to the HTTP PUT method.

4.2.6 Alternative Specification of Location

An additional facet of the GET binding is the ability to specify a URI for the location of the Resource as a result of a request. One example of this is that a SOAP HTTP POST request could return an HTTP Content-Location Header with the URI of the resource.

4.2.7 Use of & separator

The & separator is not mandatory for URL encoding. The ";" operator could also be used

4.3 Alternative Approaches

4.3.1 Noah Mendelsohn's proposal

This uses a specialized SOAP Body in the REST namespace

4.3.2 Specialized parameter for SOAP method name

One approach is to map the "getLastTradePrice" element name into a special URL paramater, perhaps dropping the "get". As in,

HTTP://example.org/stockService/&method=LastTradePrice&...

Perhaps an aesthetic, but it seems more natural to this author have the LastTradePrice, which is presumably the resource, be part of the URI and not a query parameter. A large part of this exercise seems to be to have more fine grained resources, like LastTradePrice.