# Presentation: 045443

## WSDL Specification

- WSDL = Web Service Description Language
- Similar to ASN.1 – describes the abstract on the wire data structures
- Multiple bindings to on the wire representations (not just SOAP)
- Tool Kits can build client and server stub code from WSDL

## Messages

**<!-- Message Definitions -->**
**  ****<message name="searchRetrieveRequest">**
**    ****<part name="query" nullable="true" type="xsd:string"/>**
**    ****<part name="startRecord" type="xsd:int"/>**
**    ****<part name="maximumRecords" type="xsd:int"/>**
**    ****<part name="responseSchema" nullable="true" type="xsd:string"/>**
**    ****<part name="recordSchema" nullable="true" type="xsd:string"/>**
**  ****</message>**
**  ****<message name="searchRetrieveResponse">**
**    ****<part name="searchRetrieveResponse" type="zng:searchRetrieveResponse"/>**
**  ****</message>**
**Note: Query – CQL, Result Set Name, empty for Explain**

## PortTypes

-   <!-- Port Types -->
-   <portType name="zngPort">
-     <operation name="searchRetrieve">
-       <input message="zng:searchRetrieveRequest" name="searchRetrieveRequest"/>
-       <output message="zng:searchRetrieveResponse" name="searchRetrieveResponse"/>
-     </operation>
-   </portType>

## HTTP GET Binding

- <binding name="zngURLBinding" type="zng:zngPort">
- <http:binding verb="GET"/>
-     <operation name="searchRetrieve">
-       <http:operation location=""/>
-       <input>
-         <http:urlEncoded/>
-       </input>
-       <output>
-         <mime:content type="text/xml"/>
-       </output>
-     </operation>
-   </binding>

## HTTP GET Example

- http://www.server.com/search?query=author%3aSmith
- &startRecord=0&maximumRecords=10
- &responseSchema=*zng:RS1*&recordSchema=*DC*

## SOAP/HTTP POST Binding

**  ****<binding name="zngSoapBinding" type="zng:zngPort">**
**    ****<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http/"/>**
**    ****<operation name="searchRetrieve">**
**      ****<soap:operation soapAction="" style="rpc"/>**
**      ****<input>**
**        ****<soap:body encodingStyle=**_[http://schemas.xmlsoap.org/soap/encoding/](http://schemas.xmlsoap.org/soap/encoding/)_
**             ****namespace="urn:z3950:zng_prototype1" use="literal"/>**
**      ****</input>**
**      ****<output>**
**        ****<soap:body encodingStyle=http://schemas.xmlsoap.org/soap/encoding/**
**             ****namespace="urn:z3950:zng_prototype1" use="literal"/>**
**      ****</output>**
**    ****</operation>**
**  ****</binding>**

## SOAP/HTTP Example

- <SOAP-ENV:Envelope
-     xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
-     xmlns:zng="urn:z3950:zng_prototype1“
-     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
-   <SOAP-ENV:Body>
-     <zng:query>Author:Smith</zng:query>
-     <zng:startRecord>0</zng:startRecord>
-     <zng:maximumRecords>10</zng:maximumRecords>
-     <zng:responseSchema>*zng:RS1*</zng:recordSchema>
-     <zng:recordSchema>*ONIX*</zng:recordSchema>
-   </SOAP-ENV:Body>
- </SOAP-ENV:Envelope>

## Misc.

- Encryption (if required) via https (SSL)
- Authentication via HTTP Authentication

## Response

- Actual Response Schema specified in request
- Schema either requests an XML document (for browser clients) or a SOAP wrapped XML document
- Default is “RS1”

## Response Schema RS1Overview

- <complexType name="searchRetrieveResponse">
-   <sequence>
-     <element name="resultSetReference" nullable="true" type="zng:resultSetReference"/>
-     <element name="totalHits" nullable="false" type="xsd:integer"/>
-     <element name="records" nullable="false" type="zng:records"/>
-     <element name="status" nullable="false" type="zng:status"/>
-   </sequence>
- </complexType>

## Response Schema RS1Result Set Reference

**<complexType name="resultSetReference">**
**  ****<sequence>**
**    ****<element name="resultSetName" type="xsd:string"/>**
**    ****<element name="resultSetTTL" nullable="true" type="xsd:string"/>**
**  ****</sequence>**
**</complexType>**
**Note – result set name server generated**

## Response Schema RS1Records

**<complexType base="soap:Array" name="records">**
**  ****<sequence>**
**    ****<element name="record" type="zng:record" minOccurs="0" maxOccurs="unbounded"/>**
**  ****</sequence>**
**</complexType>**
**<complexType name="record">**
**  ****<sequence>**
**    ****<element name="schema" nullable="false" type="xsd:string"/>**
**    ****<element name="recordData" type="xsd:anyType"/>**
**  ****</sequence>**
**</complexType>**

## Response Schema RS1Status

- <complexType name="status">
-   <sequence>
-     <element name="statusCode" type="xsd:int"/>
-     <element name="diagnostic" nullable="true" type="zng:diagnostic" minOccurs="0" maxOccurs="unbounded"/>
-   </sequence>
- </complexType>

## Response Schema RS1Diagnostic

**<complexType name="diagnostic">**
**  ****<sequence>**
**    ****<element name="condition" type="xsd:int"/>**
**    ****<element name="additionalInformation" nullable="true" type="xsd:string"/>**
**  ****</sequence>**
**</complexType>**
**Used as non-surrogate in Status structure**
**Used as surrogate in Record structure**

## Response Schema RS1 - Example (SOAP Wrapped)

- <SOAP-ENV:Envelope
-     xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
-     xmlns:zng="urn:z3950:zng_prototype1“
-     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
-   <SOAP-ENV:Body>
-     <zng:searchRetrieveResponse>
-       <zng:resultSetReference>
-         <zng:resultSetName>SERVER-GENERATED-NAME</zng:resultSetName>
-         <zng:resultSetTTL>16 Oct 2001 15:00:00 GMT</zng:resultSetTTL>
-       </zng:resultSetReference>
-       <zng:totalHits>2</zng:totalHits>
-       <zng:records>
-         <zng:record>
-           <zng:recordSchema>*DC*</zng:recordSchema>
-           <zng:recordData>
-             <DC:Author>Smith</DC:Author>
-             <DC:Title>A Book</DC:Title>
-           </zng:recordData>
-         </zng:record>
-        <zng:record>
-           <zng:recordSchema>zng:*diagnostic*</zng:recordSchema>
-           <zng:recordData>
-             <zng:diagnostic>
-               <zng:condition>2</zng:condition>
-               <zng:additionalInformation>Record withheld due to Access Control</zng:additionalInformation>
-             </zng:diagnostic>
-           </zng:recordData>
-         </zng:record>
-       </zng:records>
-       <zng:status>
-         <zng:statusCode>1</zng:statusCode> <!-- Partial Success -->
-         <zng:diagnostic>
-           <zng:condition>2</zng:condition>
-           <zng:additionalInformation>Records withheld due to Access Control</zng:additionalInformation>
-         </zng:diagnostic>
-       </zng:status>
-     </zng:searchRetrieveResponse>
-   </SOAP-ENV:Body>
- </SOAP-ENV:Envelope>