Websydian v6.1 online documentationOnline documentation - Websydian v6.5

SOAP Messaging Formats

Introduction

This document introduces examples of the different SOAP messaging formats that can be described in WSDLs, where to find the information in the WSDL, and the use of these formats in Websydian TransacXML applications.

This is a non-exhaustive introduction. If you need the normative and elaborate descriptions, you will need to go through the SOAP and WSDL standards. If you do that, we recommend that you also get familiar with the Basic Profile which clarifies a lot of inconsistencies in the standards.

Styles: RPC and Document

The WSDL standard describes a concept called “style”. The style indicates whether the message contains parameters and return values (RPC style messages) or whether the message contains documents (document style messages)
 

RPC style messages

The RPC style is meant to be used for remote procedure calls. The idea is to use this format when an existing function is to be provided as a web service.

It is important to notice that the payload of the SOAP message still is a valid XML document – the RPC style just provides a connection between the format of the interface and the structure of the XML document.

The top element (FunctionName) will be named after the function that is being provided as a web service. Each child element of the top element (Parameter1 – Parametern) is a parameter for the function.

In many cases, the name of the parameters are non-essential, the sequence determines which function parameter will be mapped with the specified value. See examples below.

The idea of the RPC style is to make it straight-forward to provide a function as a web service – and ultimately make it possible for development tools to do so automatically.

 

Document style messages

Where the RPC style messages can be mapped directly to a function interface, the document style messages have no such restrictions. This makes more complex messages possible.

The document style message offers more freedom in the selection of the document format than the RPC style. At the same time, it hides the interface of the function that is being made available as a service – thus making it easier to change the function without having to change the existing service.
 

Use: literal/encoded

In addition to the style concept, the WSDL standard also describes a “use” concept. This indicates whether the message parts are encoded, or whether the parts are defined by a schema.

 

Literal messages

Literal messages simply means that the format of the message is described in an external schema – often as part of a WSDL. It also means that the message itself does not contain any specifications of the message content.

The WSDL standard itself does not mandate the format of the schema describing the message, but the de-facto standard is to use W3C XML-schemas. Using W3C XML-schemas as the external description of the document format makes it easy to check whether the documents that are exchanged are valid.

 

Encoded messages

Encoded messages contain information about the content of the message itself. The normal use for this is for RPC documents, where the encoding describes the data-type of each parameter.

As encoded messages don’t refer to any external schema, it can be a problem to validate whether the document is correct according to the decided contract of information exchanged.
 

The messaging formats

The messaging format is the combination of the use and the style used by the service. By combining the use and style, you get the following four formats:

 

Document/Literal

This format is used when a service is to be called with a document that is described externally. The document can have any complexity and it does not have any relation to a function interface.

We recommend that you always use document/literal when possible, and that you encourage other parties to do the same, as document/literal ensures superior interoperability e.g. for services which are to be used by several clients/partners.

Example – SOAP document/literal request:

 

Document/encoded

This format is not used.

 

RPC/literal

This format is rare, but it does occur.

This format is used when the message relates to a parameter interface. Each part (parameter) of the message is described in an external schema.

The name of the top element of the body document specifies the function to call, while each child of this element specifies a parameter for the function.

All RPC/literal services can be implemented as document/literal services without changing the message itself.


Example – SOAP RPC/literal request:

 

RPC/encoded

The format is quite widely used.

This format is used when the message relates to a parameter interface. Each part of the message contains a “type” attribute that describes the content.

The name of the top element of the body document specifies the function to call, while each child of this element (parts) specifies a parameter for the function.

The format is disallowed by the Basic Profile. The Basic Profile describes best practices and recommendations for developing interoperable web services.

We recommend that you only use this format when you absolutely have to, typically when you have to consume an existing service from another party who has decided on this format.

One of the issues with the RPC/encoded format is that the SOAP standard describes a “SOAP-encoded array” to handle the case where one or more parameters are multi-occurrence structures. Use of these arrays compromises interoperability as some tools don’t handle these structures – and the tools that do seem to implement the arrays in different ways.

Example – a simple SOAP RPC/encoded request:


 

Finding The information in the WSDL

The use and style attributes for a service can be found in the binding section of the WSDL.

The example below defines two different operations (functions) ReturnList and ReturnOffer, the style attribute (document) is defined in the soap:binding element – so it is valid for both operations. Both operation has an input and an output message – both messages are specified as having the “literal” use.

 

The style can also be defined for each operation (in the soap:operation element). This means that you can described both document and rpc operations in the same binding.

The use can also be defined for each operation (in the soap:operation element). This means that you can define that all the messages used for the operation is either literal or encoded.
 

TransacXML and messaging formats

When working with web services, you always have to distinguish between being the provider and being the consumer of the web service.

When you provide the web service, you have to be able to make the service available for the consumers, and you must be able to generate a WSDL file that enables the consumers to call the service.

As a provider, you will normally have the option to determine which format the service should have.

When you consume the web service, you should be able to import the WSDL file, and based on these definitions call the service. As a consumer you will normally not be able to determine the format of the service. Usually you will have to just implement the format defined for the service by the provider.
 

When providing a service

Document/literal

All services provided using TransacXML are document/literal services. TransacXML can generate WSDL files for these services based on the Plex definitions – all WSDL files generated by TransacXML describes the services as being document/literal.

 

RPC/literal

As all messages used for RPC/literal services can be defined as document/literal messages, TransacXML is capable of providing services that has been defined as RPC/literal services. However, if you generate a WSDL for the service, it will describe the service as a document/literal service.

 

RPC/encoded

TransacXML is capable of providing most RPC/encoded services – but it will take often take some effort to get the definitions right in the Plex model.

TransacXML cannot generate RPC/encoded WSDLs.

You should only try to use this if you absolutely have to (if you need to provide a service to a consumer who has defined the format of the service).

 

When consuming a service

Document/literal

TransacXML can create the Plex document definitions based on a document/literal WSDL.

Plex can call a document/literal service.


 

RPC/literal

TransacXML can create the Plex document definitions based on an RPC/literal WSDL.

Plex can call an RPC/literal service.


 

RPC/encoded

TransacXML can create Plex document definitions based on an RPC/encoded WSDL. However, SOAP-encoded arrays are not fully handled. You should be able to create the rest of the definitions manually – but this can be quite complex.

TransacXML can call RPC/encoded services.

Note that the SOAP standard allows encoding using other encoding methods. TransacXML only supports SOAP-encoding.
 

Further reading