This JEP defines methods for transporting SOAP messages over XMPP.
NOTICE: This JEP is currently within Last Call or under consideration by the Jabber Council for advancement to the next stage in the JSF standards process. For further details, visit <http://www.jabber.org/council/queue.php>.
Status: Proposed
Type: Standards Track
Number: 0072
Version: 0.3
Last Updated: 2004-05-10
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, SOAP 1.2
Supersedes: None
Superseded By: None
Short Name: None
Email: fabio.forno@polito.it
JID: sciasbat@jabber.linux.it
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
SOAP [1] is a lightweight protocol that defines a method for the exchange of messages independently from the programming language and platform. For interoperability, the SOAP specification is also agnostic about possible transport protocols, though almost all existing implementations use mainly HTTP.
The primary limitation of HTTP consists in the fact that HTTP-based message exchanges allow only synchronous RPC-like calls. To overcome this limitation, SMTP is often used to carry asynchronous messages, but it is a complex protocol and inefficient for passing short and frequent messages that should be delivered in close to real time.
Thus XMPP (see XMPP Core [2]) can be the ideal transport protocol for many of the application fields of web services, since it can carry efficiently and reliably both types of messages, synchronous and asynchronous. Moreover, XMPP-based web services will not need complex support protocols, such as WS-Routing [3] and WS-Referral [4], in order to deliver messages to entities that cannot be identified by static public IP addresses.
Since SOAP envelopes can transport both RPC-like calls and asynchronous one-way messages, both <iq/> and <message/> with <soap/> child elements are used in order to assure maximum flexibility. It is up to implementors to choose the appropriate stanza type for their applications:
These approaches are defined in the following sections.
The transport with <iq/> stanzas is performed in a way similar to that described for XML-RPC in Jabber-RPC [5]. Request envelopes are carried by <iq/> stanzas of type "set", and answer envelopes by <iq/> stanzas of type "result". SOAP errors are encoded with standard SOAP envelopes, and returned in stanzas of type "error" with appropriate codes in order to distinguish them from errors specific to the XMPP transport layer.
Each <iq/> stanza MUST contain a unique SOAP envelope as the first-level child element, since it already represents a properly namespaced XML subtree qualified by the 'http://schemas.xmlsoap.org/soap/envelope' namespace.
Example 1. A SOAP request inserted into an IQ stanza
<iq from='requester@company-a.com/soap-client'
id='soap1'
to='responder@company-a.com/soap-server'
type='set'>
<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
<env:Body>
<m:GetLastTradePrice
xmlns:m='Some-URI'
env:encodingStyle='http://www.w3.org/2003/05/soap-encoding'>
<m:symbol>DIS</m:symbol>
</m:GetLastTradePrice>
</env:Body>
</env:Envelope>
</iq>
Example 2. A SOAP response, inserted into an IQ stanza
<iq from='responder@company-a.com/soap-server'
id='soap1'
to='requester@company-a.com/soap-client'
type='result'>
<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
<env:Body>
<m:GetLastTradePriceResponse
xmlns:m='Some-URI'
env:encodingStyle='http://www.w3.org/2003/05/soap-encoding'>
<m:Price>34.5</m:Price>
</m:GetLastTradePriceResponse>
</env:Body>
</env:Envelope>
</iq>
Message stanzas MUST carry one SOAP envelope as a first-level child element, as is done with <iq/> stanzas; the only difference is given by the different semantics and benefits of <message/> stanzas, such as store and forward. The 'id' attribute MUST be used to track SOAP messages and eventually associate errors or answers to the relative requests.
Example 3. A SOAP envelope carrying an RDF descritpion of a RSS feed inserted into a message stanza
<message to='endpoint@company-a.com/soap-client' id='soap2'>
<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
<env:Body>
<rdf:RDF
xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
xmlns='http://my.netscape.com/rdf/simple/0.9/'>
<channel>
<title>Slashdot</title>
<link>http://slashdot.org/</link>
<description>News for nerds, stuff that matters</description>
</channel>
<item>
<title>Jabber/XMPP now supports SOAP</title>
<link>http://slashdot.org/somepath</link>
</item>
</rdf:RDF>
</env:Body>
</env:Envelope>
</message>
SOAP provides its own encoding scheme for errors due to message processing or application execution, and it uses SOAP envelopes for reporting. The SOAP HTTP binding specifications [6] map these errors to corresponding HTTP status codes. Since <iq/> stanzas have the same behavior as typical HTTP request/response interactions, SOAP faults are mapped in a similar way in <iq/> stanzas of type "error". This approach should facilitate the design of HTTP<->XMPP gateways for web services. The following table provides a mapping between SOAP, HTTP, and <iq/> error codes (for Jabber/XMPP error syntax, see XMPP Core and Error Condition Mappings [7]).
Table 1: Mapping of SOAP Error codes
| SOAP Error | HTTP Code | Short Description | IQ Error Description |
|---|---|---|---|
| env:VersionMismatch | 500 | Internal server error | <internal-server-error/> |
| env:MustUnderstand | 500 | Internal server error | <internal-server-error/> |
| env:Sender | 400 | Bad request | <bad-request/> |
| env:Receiver | 500 | Internal server error | <internal-server-error/> |
| env:DataEncodingUnknown | 500 | Internal server error | <internal-server-error/> |
Example 4. A SOAP response with error, inserted into an IQ stanza
<iq type='error' to='requesterr@company-a.com/soap-client' id='soap1'>
<env:Envelope
xmlns:env='http://www.w3.org/2003/05/soap-envelope'
xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
<env:Body>
<env:Fault>
<env:Code>
<env:Value>env:Sender</env:Value>
<env:Subcode>
<env:Value>rpc:BadArguments</env:Value>
</env:Subcode>
</env:Code>
<env:Reason>
<env:Text xml:lang='en-US'>Processing error</env:Text>
</env:Reason>
<env:Detail>
<e:myFaultDetails xmlns:e='http://travelcompany.example.org/faults'>
<e:message>Name does not match card number</e:message>
<e:errorcode>999</e:errorcode>
</e:myFaultDetails>
</env:Detail>
</env:Fault>
</env:Body>
</env:Envelope>
<error code='500' type='cancel'>
<internal-server-error xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Since errors could occur also for asynchronous interaction using <message/> stanzas, the same error mapping scheme of <iq/> stanzas SHOULD be used. A typical situation where this can happen is a service receiving regular messages reporting remote sensor readings with asynchronous messages. If the controlling device detects some malfunctions in the sensors, it can send a <message/> stanza of type error to the monitoring application.
When errors are due to the XMPP transport protocol, and not to the application layer defined by SOAP, errors MUST be reported with standard XMPP error codes only (i.e., not including the SOAP envelope).
Example 5. An XMPP entity reports that it cannot handle SOAP messages
<iq type='result' to='requester@company-a.com/soap-client' id='soap1'>
<error code='503' type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Because XMPP does not require the parsing of arbitrary and complete XML documents, and does not require implementations to support the full XML specification, transported SOAP envelopes MUST comply with the XML restrictions specified in Section 11 ("XML Usage Within XMPP") of XMPP Core. In particular, all envelope elements MUST be properly namespaced (SOAP allows elements within the default namespace, but they are deprecated since SOAP 1.2).
SOAP envelopes may contain arbitrary data encoded in valid XML, and also byte arrays encoded with SOAP-specific elements. The SOAP specification recommends to encode byte arrays in Base 64 (see RFC 3548 [8]), with the result that envelopes with binary data can be transported within regular XMPP stanzas. All the remaining PCDATA MUST be encoded with UTF-8 in order to match the XML stream encoding.
Binary data could grow significantly in size, and messages carrying it could be penalized by servers with karma settings tuned for normal textual chats. The problem could be bypassed by servers having special karma settings for larger messages, or by SOAP-enabled entities being implemented as components; however, server-to-server communications risk becoming a serious bottleneck, especially in terms of latency and responsiveness when too many large messages are sent.
However, SOAP provides several methods to transport binary data as attachments; the most common are:
The first method, using the file link in the envelope, is a general one, and can be used by XMPP clients if they are able to retrieve the file (e.g, using Out-of-Band Data [12]). However, the other methods cannot be used directly with XMPP, since MIME messages do not fit in XML streams and WS-Attachments and BEEP are just other transport protocols.
Example 6. SOAP attachment using MIME
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
start="<claim061400a.xml@claiming-it.com>"
Content-Description: This is the optional message description.
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim061400a.xml@claiming-it.com>
<?xml version='1.0' ?>
<env:Envelope
xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
<env:Body>
..
<theSignedForm href='cid:claim061400a.tiff@claiming-it.com'/>
..
</env:Body>
</env:Envelope>
--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim061400a.tiff@claiming-it.com>
...
For the transport of binary data, the file transfer method described in File Transfer [13] SHOULD be used.
Example 7. SOAP attachment using file transfer
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
<si xmlns='http://jabber.org/protocol/si'
id='a0'
mime-type='img/tiff'
profile='http://jabber.org/protocol/si/profile/file-transfer'>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='claim061400a.tiff@claiming-it.com'
size='100228'
hash='552da749930852c69ae5d2141d3766b1'
date='1972-02-02T02:56:15Z'/>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field var='stream-method' type='list-single'>
<option><value>http://jabber.org/protocol/bytestreams</value></option>
<option><value>http://jabber.org/protocol/ibb</value></option>
</field>
</x>
</feature>
</si>
</iq>
WSDL [14] provides a machine-readable, formal description of web services operations, protocol bindings, and end points (i.e., network addresses). This description is aimed at specifying a loose coupling of SOAP envelopes and their transports, in order to maintain their independence and flexibility. Thus the definition of an XMPP SOAP transport through WSDL is straightforward. The following elements are relevant for the XMPP transport:
Example 8. Example of WSDL definition for a SOAP-based translator over XMPP
<definitions
name='BabelFishService'
targetNamespace='http://www.example.org/services/BabelFishService.wsdl'>
...
<binding name='BabelFishBinding' type='tns:BabelFishPortType'>
<soap:binding style='rpc' transport='http://jabber.org/protocol/soap'>
<operation name='Translate'>
<soap:operation soapAction='urn:googleBabelFish#BabelFish'/>
<input>...</input>
<output>...</output>
</operation>
</binding>
<service name='BabelFishService'>
<documentation>
Translates text using Google's Babelfish.
</documentation>
<port name='BabelFishPort' binding='tns:BabelFishBinding'>
<soap:address location='xmpp:babel@jabber.example.org'/>
</port>
</service>
</definitions>
Although there is no standard procedure to publish WSDL documents, usually they are made available through HTTP at some URL discoverable with public registries such as UDDI servers. WSDL descriptions for XMPP bindings MAY follow the same publishing process, or MAY be discoverable through Jabber/XMPP specific mechanisms such as Service Discovery [16] or Publish-Subscribe [17].
This section is non-normative.
This section provides an example of a gateway between XMPP-based and HTTP-based web services and it is not meant to be part of the SOAP over XMPP specifications. Its purpose is only to demonstrate how HTTP and XMPP can be used together in web services, and how to invoke any web services already accessible through HTTP from XMPP clients.
WS-Routing, whose aim is to dynamically compose SOAP message paths and processing sequences, can be used in order to reference web services outside of an XMPP network from within it. WS-Routing extends SOAP Envelope Headers with the <path/> element, which specifies the following for the message: the sender's URL (<from/>), the final destination's URL (<to/>), a forward (<forward/>) path with an arbitrary number of intermediaries (<via/>), and an optional return path (<reverse/>). Each intermediary MUST process the <path/> header and update it accordingly to the already performed path; moreover it MAY process the Body of the message.
A SOAP message originated by an XMPP entity ('xmpp:orig@A.com/soap'), and directed to an end point accessible through HTTP ('http://C.com/some/endpoint'), could be built using a <path/> header having:
Then the SOAP message can be sent within an <iq/> stanza to the gateway's JID. The gateway processes the SOAP headers, and looking through the headers it discovers that it must act only as intermediary. From the <to/> element it reads the URL of the final end point, extracts the SOAP action, changes the path removing the step already performed, and issues an HTTP request with the modified envelope and appropriate HTTP headers. Once it has received a response, it prepares a new <iq/> stanza of type "result" or "error" and sends the result to the original requester. The following example shows the possible SOAP headers of the described process.
Example 9. Gateway-generated SOAP headers
<S:Envelope xmlns:S='http://www.w3.org/2003/05/soap-envelope'>
<S:Header>
<m:path xmlns:m='http://www.soap.org/path'>
<m:action>http://www.im.org/chat</m:action>
<m:to>http://C.com/some/endpoint</m:to>
<m:forward>
<m:via>xmpp:soapgw@B.com/soap</m:via>
</m:forwawd>
<m:reverse>
<m:via/>
</m:reverse>
<m:from>xmpp:orig@A.com/soap</m:from>
<m:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</m:id>
</m:path>
</S:Header>
<S:Body>
...
</S:Body>
</S:Envelope>
SOAP has several support protocols that help ensure message integrity and confidentiality (WS-Security [18]) as well as transaction management for failing message exchanges (WS-Transaction [19]). These protocols are all based on SOAP messages and take into account that the underlying protocols can be unreliable and not trusted, thus there are no arguments against their application with XMPP. Alternatively, implementations MAY use native XMPP security such as XMPP E2E [20].
No interaction with the Internet Assigned Numbers Authority (IANA) [21] is required as a result of this JEP.
The Jabber Registrar [22] shall include 'http://jabber.org/protocol/soap' in its registry of protocol namespaces.
Because the SOAP envelope is included as a first-level child element of an <iq/> or <message/> stanza via standard XMPP extension mechanisms, an XML schema is not required for this JEP. An XML schema for the SOAP envelope element is provided in the SOAP 1.2 Specification.
1. SOAP 1.2 Specification <http://www.w3.org/TR/SOAP/>.
2. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
3. WS-Routing Specification <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-routing.asp>.
4. WS-Referral Specification <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-referral.asp>.
5. JEP-0009: Transporting XML-RPC over Jabber <http://www.jabber.org/jeps/jep-0009.html>.
6. SOAP Version 1.2 Part 2: Adjuncts <http://www.w3.org/TR/soap12-part2/>.
7. JEP-0086: Error Condition Mappings <http://www.jabber.org/jeps/jep-0086.html>.
8. RFC 3548: The Base16, Base32, and Base64 Data Encodings <http://www.ietf.org/rfc/rfc3548.txt>.
9. SOAP Messages with Attachments <http://www.w3.org/TR/SOAP-attachments>.
10. WS-Attachments <http://www.watersprings.org/pub/id/draft-nielsen-dime-soap-01.txt> (work in progress).
11. RFC 3080: The Blocks Extensible Exchange Protocol Core (BEEP) <http://www.ietf.org/rfc/rfc3080.txt>.
12. JEP-0066: Out of Band Data <http://www.jabber.org/jeps/jep-0066.html>.
13. JEP-0096: File Transfer <http://www.jabber.org/jeps/jep-0096.html>.
14. WSDL 1.1 Specification <http://www.w3.org/TR/wsdl>.
15. A Uniform Resource Identifier (URI) Scheme for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-uri-06.txt> (work in progress).
16. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
17. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.
18. WS-Security <http://msdn.microsoft.com/ws/2002/04/Security/>.
19. WS-Transaction <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-transaction.asp>.
20. RFC 3923: End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/rfc/rfc3923.txt>.
21. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
22. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END