RE: HTTP Binding example for the Primer

Hi David,
 
Thanks a lot for the contribution. Don't worry about the XML format, I
will doing the formating and incorporate it into the primer.

Best Regards,
Kevin
  

 

  _____  

From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] 
Sent: Thursday, Mar 31, 2005 4:15 PM
To: www-ws-desc@w3.org
Subject: HTTP Binding example for the Primer



I've created a bunch of examples for the Primer.  A checkAvailability
GET, ReservationDetails GET and PUT, and 2 forms of ReservationList GET.
This shows GETs and PUTs, as well as using a query type for use in a
URI.  My apologies for not putting this into xml-spec nor providing
perhaps the most complete examples or text, but at least the content is
there.

 

4.3.3 Extensions for  HTTP Binding

 

As mentioned in section 2.5, WSDL 2.0 offers great flexibility in
binding to SOAP message formats as well as HTTP.  The GreatH service can
be deployed to HTTP such that an HTTP GET can return the flight
availability, as shown below:

 

  <binding name="reservationHTTPBinding" 

      interface="tns:reservationInterface"

      whttp:methodDefault="GET">

 

  <operation ref="tns:opCheckAvailability"

    whttp:location="{tCheckAvailability}"  >

 

  </binding>

 

  <service name="reservationService" 

    interface="tns:reservationInterface">

 

    <!-- HTTP 1.1 GET End Point -->

    <endpoint name="reservationEndpoint" 

      binding="tns:reservationHTTPBinding"

      address="http://greath.example.com/2004/"/>

 

 

The default Binding Rules for HTTP specify that the default input
serialization for GET is application/x-www-form-urlencoded.  A sample
URI is

http://greath.example.com/2004/?checkInDate=5-5-5
<http://greath.example.com/2004/?checkInDate=5-5-5&checkOutDate=6-6-5&ro
omType=foo> &checkOutDate=6-6-5&roomType=foo

 

Each of the elements in the tCheckAvailability type is serialized into
the query parameters.

 

It is also possible to serialize a subset of the tCheckAvailability type
by using appending a "/" in the whttp:location, as in:

 

<operation ref="tns:opCheckAvailability"

    whttp:location="bycheckInDate/{checkInDate/}"  >

 

This serializes to http://greath.example.com/2004/bycheckInDate/5-5-5.  

 

5.11.3 Reservation Details Web Service using HTTP transfer

 

As each reservation has a distinct URI, the Reservation Details Web
service can be offered using HTTP GET and HTTP PUT.

 

<binding name="reservationDetailsHTTPBinding"

        interface="tns:reservationDetailsInterface"

        

        <operation ref="tns:retrieve"

            whttp:method="GET" />

 

        <operation ref="tns:update"

            whttp:method="PUT" />

 

    </binding>

 

As with the earlier examples, a service and endpoint elements are not
provided because the reservation List Web service provides the
endpoints.  

 

5.11.4 Reservation List Web service using HTTP GET

 

The SOAP version of the Reservation List offers 4 different search
operations.  These can also be expressed as various parameters in a URI
used by HTTP Get.

 

<binding name="reservationListHTTPBinding"

        interface="tns:reservationListInterface"

        whttp:methodDefault="GET">

 

        <operation ref="tns:retrieve"

            whttp:location="" />

 

        <operation ref="tns:retrieveByConfirmationNumber"

            whttp:location="/ConfirmationNumber/{confirmationNumber/}"
/>

 

        <operation ref="tns:retrieveByCheckInDate"

            whttp:location="/CheckInDate/{checkInDate/}" />

 

        <operation ref="tns:retrieveByCheckOutDate"

            whttp:location="/CheckOutDate/{checkOutDate/}" />

 

    </binding>

 

    <endpoint name="reservationListEndpoint"

            binding="tns:reservationListHTTPBinding"

            address="http://greath.example.com/2004/reservationList" />

 

  

A retrieval by Confirmation Number URI would look like
http://greath.example.com/2004/reservationList/ConfirmationNumber/HSG635

 

 

Alternatively, a single Query type may be provided.  This query type is
a sequence of optional items.  Any items in the sequence are serialized
into the URI query string.  A query sequence for any of
ConfirmationNumber, checkInDate, checkOutDate is

 

<element name="reservationQuery">

        <annotation>

            <documentation>

                A reservation contains the confirmation number, check-in

                and check-out dates, and a reference to a Reservation

                Details Web service.

            </documentation>

        </annotation>

        <complexType>

            <sequence>

                <element ref="details:confirmationNumber"
minOccurs="0"/>

                <element ref="details:checkInDate" minOccurs="0"/>/>

                <element ref="details:checkOutDate" minOccurs="0"/>/>

            </sequence>

            </sequence>

        </complexType>

    </element>

 

The WSDL service that offers this type serialized as a parameter is:

 

<interface name="reservationListInterfaceWithQuery">

 

        <operation name="retrieveByReservationQuery"

            pattern="http://www.w3.org/2004/03/wsdl/in-out">

            <input messageLabel="In"

                element="details:ReservationQuery" />

            <output messageLabel="Out" element="list:reservationList" />

        </operation>

 

    </interface>

 

<binding name="reservationListQueryHTTPBinding"

        interface="tns:reservationListInterfaceWithQuery"

        whttp:methodDefault="GET">

 

        <operation ref="tns:retrieveByReservationQuery"

            whttp:location="/{ReservationQuery}}" />

 

    </binding>

 

    <endpoint name="reservationListEndpoint"

            binding="tns:reservationListHTTPBinding"

            address="http://greath.example.com/2004/reservationList" />

 

 

Various URIs are

http://greath.example.com/2004/reservationList/ReservationQuery?confirma
tionNumber=HSG635

http://greath.example.com/2004/reservationList/ReservationQuery?checkInD
ate=06-06-05

 

It is important to observe that using the URI serialization can result
in very flexible queries and few operations.  The previous discrete SOAP
operations are collapsed into one "parameterized" operation.