Directory Services

SOAP Request and Response Binding

The SOAP Request and Response binding method uses SOAP to bind to a server. SOAP is a lightweight protocol for data exchange in a distributed environment and consists of:

An envelope that defines a framework for describing what is in a message and how to process it
A set of encoding rules for expressing instances of application-defined data types
A convention for representing remote procedure calls and responses

SOAP therefore defines the XML format for messages. For example, if you have a well-formed XML fragment consisting of a DSML V2 document enclosed in a pair of SOAP elements, you have a SOAP message.

This implementation of SOAP request/response binding uses HTTP 1.1 and HTTPS 1.1 as a transport for DSML V2 requests and responses. The version of SOAP used for this binding is SOAP 1.1.

The following illustration shows the data flow for a DSML V2 request and response.

In the preceding illustration, a client makes a request using the SOAP (XML) over HTTP protocol. That request goes to a server running IIS, where it is routed to a DMSL V2 ISAPI extension. There, it is converted to LDAP commands, which are sent on to the directory services. The response occurs in a reverse fashion, with the response returning to the client via the SOAP over HTTP response.

Every SOAP request and response must have an envelope element that contains a body element, and a body element that contains the DSML V2 payload. The following code example shows the general form of a SOAP message.

<Envelope>
	<Header>
		All SOAP header elements go here
	</Header>
	<Body>
		The DMSL 2.0 payload (document) goes here
	</Body>
</Envelope>

The <Envelope> and <Body> elements are required, but the <Header> element is optional. For more information about the SOAP specification, see http://www.w3.org/TR/SOAP and Using DSML Services for Windows.

The following code example shows a request/response message sequence.

ccc<!--  **** DSMLv2 Request ****** --> 
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/">
   <se:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
	<batchRequest> 
		 <modifyRequest> … </modifyRequest>
		 <addRequest> … </addRequest>
		…
	</batchRequest>
   </se:Body> 
</se:Envelope>


<!--  **** DSMLv2 Response ****** -->
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
			 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
			 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
			 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soap:Body> 
	<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core"
					 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
					 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		 <modifyResponse> … </modifyResponse>
		 <addResponse> … </addResponse>
		 …
	</batchResponse>
   </soap:Body>
</soap:Envelope>

In the preceding example, be aware of the following:

The namespace for DSML V2 is urn:oasis:names:tc:DSML:2:0:core. This namespace is used at the top-level element of the <Body> of each SOAP request and is returned in the DSML V2 payload response. Default namespace designations may be used.
All SOAP requests and responses in this binding must use the XML encoding UTF-8.
Each SOAP request body contains a single DSML <batchRequest>.
Each SOAP response body contains a single DSML <batchResponse>.