1.3 Overview

IMDA is an extension to the WS-Transfer protocol [WXFR]. WS-Transfer permits the XML [XML10] representation of resources to be created, modified, retrieved, and deleted. WS-Transfer operates at the level of granularity of the complete representation of an entire resource. That is, when the resource is retrieved, the complete contents of the resource must be retrieved. There is no mechanism in WS-Transfer to specify that only a portion of the resource should be retrieved or what that portion should be. Similarly, when the resource is to be created or modified, the client must supply a new XML representation for the entire resource. During the creation of a resource, there is no means by which the caller can specify only the portion of interest of the resource and allow the server to fill in the remainder of the representation with suitable defaults. Nor is there a mechanism during resource modification by which the caller can specify only the portion of the representation that should be changed and what the new contents for just that portion should be.

Such operations can be difficult for a client to use. For example, if a client wants to modify a single portion (for example, the portion specifying a person's given name) on a resource representing that person, the client would need to read the entire resource, change the value of that one portion of the representation, and then send the entire representation back to the server. The result is increased network traffic and bandwidth consumption. In a usage such as a directory service, where each resource might be a directory object that could contains dozens or hundreds of attributes, and each attribute could contain multiple values, a more efficient protocol is desirable. The IMDA extensions to WS-Transfer [WXFR] were designed for this purpose.

IMDA adds protocol extensions to WS-Transfer to permit it to work at the level of granularity of portions of the representation of a resource. It allows the client to specify just the portion of the resource to be created, modified, or retrieved. To do so, IMDA defines such fine-grained extensions to the following WS-Transfer Web Services Description Language (WSDL) operations:

  • Put

  • Create

  • Get

Requests that make use of IMDA extensions can be identified by the presence of an IMDA-specific SOAP header.

Additionally, the specification of WS-Transfer provides only a small set of SOAP faults for a server to return. This set is insufficient for many error conditions that a server would need to report to the client, forcing the server to invent its own nonstandard SOAP fault codes. IMDA extends the WS-Transfer set of faults by specifying additional SOAP faults that a server is permitted to return to the client to indicate that an error occurred while processing the request. The intent is to improve interoperability between clients and servers by providing a standardized set of errors that both sides of the communication session can understand. IMDA specifies SOAP faults for the three WS-Transfer operations listed in this section as well as for the WS-Transfer Delete operation (which is not otherwise extended by IMDA).