Introduction to SOAP and Web Services

A Web Service is programmable application logic accessible using standard Internet protocols. Web services combine the best aspects of component-based development and the Web. Like components, Web services represent black-box functionality that can be reused without worrying about how the service is implemented. Unlike current component technologies, Web services are not accessed via object-model-specific protocols, such as the distributed Component Object Model (DCOM), Remote Method Invocation (RMI), or Internet Inter-ORB Protocol (IIOP). Instead, Web services are accessed via ubiquitous Web protocols and data formats, such as Hypertext Transfer Protocol (HTTP) and Extensible Markup Language (XML). Furthermore, a Web Service interface is defined strictly in terms of the messages the Web Service accepts and generates. Consumers of the Web Service can be implemented on any platform in any programming language, as long as they can create and consume the messages defined for the Web Service interface.

SOAP is the Simple Object Access Protocol. Soap is the communications protocol for XML Web services. The current version is 1.2, and the actual specification can be found at www.w3.org/tr/soap. SOAP is based on XML and describes a messaging format for machine-to-machine communication. It also contains several optional sections describing method calls (RPC) and detailing the sending of SOAP messages over HTTP.

 

 

XX1 Operations and Documents

Web Service operations can be "document" oriented or "remote procedure call (RPC)" oriented.

If an operation in the WSDL file is document-oriented, the input (request) and output (response) messages specified for that operation contain XML documents.

RPC-oriented operations have input messages that contain the operations' input parameters and output messages that contain the operations' results.

XX1 operations are always document-oriented, where the root node of the XML document designates the operation, function or business procedure that is to be invoked. The XML documents are described in separate XML Schemas (XSD).

XX1 SOAP messages also specify a transaction header - it contains the so called Transaction Control Data ("TC"). The TC is typically used to identify the sender and specify the target system.

 

 

SOAP Methods

Since XX1 operations are document oriented, XX1 defines only a few SOAP methods that rarely change. The XX1 Server implements the following SOAP methods that can be used by a client:

  • XXTransaction:
    • invokes a server side script, that contains the business logic to process the request. The script usually transforms data to supported standards and applies business logic.
  • GetProviderSession:
    • locks a session on the target host system. The underlying host provider adapter implements the actual details of session management if any.
    • GetProviderSession will return a context ID which must be included in all subsequent transactions (XXTransaction, ProviderTransaction) to be performed within that session and in the final ReleaseProviderSession request.
  • ProviderTransaction:
    • passes a request directly on to the target host system as is without transformation or applying any business logic.
  • ReleaseProviderSession:
    • releases a session on the target host system. The underlying host provider adapter implements the actual details of session management if any.
  • RemoteAdmin:
    • provides an XML API for remote monitoring and maintenance of the server system.

 

 

SOAP XML Structure

Apart from the default namespaces for the SOAP Envelope there are some specific rules for the content of the SOAP Header and SOAP Body section for XX1.

SOAP Envelope:

Default SOAP Envelope namespaces
 <SOAP-ENV:Envelope
       xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
       SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
       xmlns:xsd="http://www.w3.org/1999/XMLSchema/"
       xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance/">
    <SOAP-ENV:Header>
       ...
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
       ...
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

SOAP Header:

XX1 specific namespaces

In the SOAP header the Transaction element that contains the TC MUST contain a namespace prefix named "t". Any other name for the namespace prefix will make the transaction to fail with an error message. The content of the namespace is not relevant. 

<SOAP-ENV:Header>
    <t:Transaction xmlns:t="XXServer">
        <tc>
            <iden u="USER" p="PASSWORD" />
            <provider session="SESSIONNAME">PROVIDERNAME</provider>
            <trace>YOURTRACENAME</trace>
        </tc>
    </t:Transaction>
</SOAP-ENV:Header>

 

SOAP Body

XX1 specific namespaces

In the SOAP body the XXTransaction, ProviderTransaction, GetProviderSession, ReleaseProviderSession or RemoteAdmin elements MUST contain a namespace prefix named "ns1". Any other name for the namespace prefix will make the transaction to fail with an error message. The content of the namespace is not relevant.

There are two subelements possible:

  • CONTEXT : contains the session context ID if you work in a sessioned workflow
  • REQ : contains the message content
<SOAP-ENV:Body>
    <ns1:ProviderTransaction xmlns:ns1="XXServer">
        <CONTEXT />
        <REQ>
            <QueueProcessing_3>
                ...
            </QueueProcessing_3>
        </REQ>
    </ns1:ProviderTransaction>
</SOAP-ENV:Body>

HTTP Header

Basic non-sessioned XX1 SOAP request messages have the following HTTP header format: 

POST /xxs HTTP/1.1
Host: test.pass-xml.com:8800
Content-Type: text/xml; charset="utf-8"
Connection: close

Compression

When sending compressed request messages the following HTTP header formats must be used: 

POST /xxs HTTP/1.1
Host: test.pass-xml.com:8800
Content-Type: text/xml; charset="utf-8"
Content-Length: 110
Text-Length: 565
Content-Encoding: zlib
Connection: close

When requesting compressed responses from XX1 to be returned, the Accept-Encoding HTTP-header entry must be specified. The following values are supported:

  • deflate (HTTP standard conform option, where XX1 will return the response ZLIB compressed without first two bytes according to the deflate specification in RFC 1951 and marks the content in the HTTP header of the response as:
    Content-Encoding: deflate
  • zlib (proprietary option for backward compatibility, where XX1 will return the response ZLIB compressed according to ZLIB specification in RFC 1950) and marks the content in the HTTP header of the response as: 
    Content-Encoding: zlib

Other values e.g. gzip are not supported yet, but support can be added on request.

Example for an HTTP request that requests deflate-compressed responses: 

POST /xxs HTTP/1.1
Host: test.pass-xml.com:8800
Content-Type: text/xml; charset="utf-8"
Accept-Encoding: deflate
Connection: close

 

For HTTP response messages of compressed responses the Content-Length specifies the number of bytes of the compressed data and Text-Length indicates the original size prior to compression. The HTTP response is: 

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Encoding: deflate
Content-Length: 758
Text-Length: 3066

Session handling

When working with sessions in a load balanced XX1 environment with multiple XX1 servers it is required to make the HTTP header keeping the connection alive with the same XX1 server instance where the session was created on and to ensure that all followup requests in that session are ending on the same XX1 server instance.

Hereby it is important to understand the differences in the handling between HTTP/1.0 and HTTP1.1 in how to keep a connection alive.