RE: Sample Application described in WSDL using HTTP binding and s howing messages from Asir Vedamuthu on 2004-06-22 (www-ws-desc@w3.org from June 2004)

From: Asir Vedamuthu <asirv@webmethods.com>
Date: Tue, 22 Jun 2004 11:52:42 -0700
To: 'David Orchard' <dorchard@bea.com>, www-ws-desc@w3.org
Message-ID: <5B10E50E14A4594EB1B5566B69AD94072EF5CD@maileast>
One of your observations is,

"Overall, there is an explosion of schemas and operations that are needed
because of the binding. I think this kind of sucks and comes close to making
the http binding useless as it stands."

I am not surprised by your statement, "there is an explosion of schemas and
operations that are needed". XML Schema is a language for describing the
structure and contents of XML documents. In this case, we are using XML
Schema + binding for describing the path and query component of URI data
model. This is a stretch. But, not free though. It comes with a certain
level of pain :-(

I am surprised by your statement, "comes close to making the http binding
useless". I request you to explain why?

I would expect the following restrictions (in addition to what is spelled
out in RPC style [1]) on XML schema for URI style:

(a) {target namespace} of an element declaration [2] in the complex type
that defines the body of an input element MUST be absent.

Why? In David's example,
"<xs:element name="ArtistQuery">
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="tns:ArtistIDBase">
          <xs:sequence>
            <xs:element name="Name" type="xs:string" minOccurs="0"/>
            <xs:element name="Genre" type="xs:string" minOccurs="0"/> .."

QName of element decl 'Genre' is,
 [target namespace] = http://www.w3.org/2002/ws/music/2004/
 [name] = Genre

I am not aware of a mechanism to serialize this QName to URI path/query
component.


(b) {type definition} of an element declaration [2] in the complex type that
defines the body of an input element MUST be a simple type.

Why? I am not aware of a mechanism to serialize a complex type value to URI.
In part 3, I read a statement close to this, but not quite the same - "If
the children elements of the input sequence are defined using an XML Schema
type, they MUST derive from xsd:simpleType, .." [3]. 'xsd:simpleType' is the
xml rep of a simple type. There isn't any simple type whose name is
xsd:simpleType.


(c) {type definition} of an element declaration [2] in the complex type that
defines the body of an input element MUST NOT be a xs:QName, xs:NOTATION, or
any simple type derived from xs:QName or xs:NOTATION. 

Why? Lexical rep of these types are context sensitive, aka namespace binding
context. I am not aware of a mechanism to specify namespace bindings (other
than XPointer xmlns() scheme) in a URI path/query component.


PS: I don't know why URI style places a restriction on binary simple types:
"MUST NOT derive from xsd:hexBinary or xsd:base64Binary" [3]. Any thoughts?

[1]
http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html#RPCStyle
[2] http://www.w3.org/TR/xmlschema-1/#Element_Declaration_details
[3]
http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20-bindings.html
#_operation_uri_style

Asir

-----Original Message-----
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of David Orchard
Sent: Tuesday, June 22, 2004 1:23 PM
To: www-ws-desc@w3.org
Subject: RE: Sample Application described in WSDL using HTTP binding and
showing messages



As promised, I've updated the music example.  I fixed the bugs that Asir
pointed out, added a number of design notes, put more comments in the WSDL,
added another couple of examples, added HTML formatting.

http://www.pacificspirit.com/Authoring/wsdl/ArtistWSDL2uriformencoding.html

Hopefully this will be more useful to reviewers.

Cheers,
Dave

> -----Original Message-----
> From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]On
> Behalf Of David Orchard
> Sent: Wednesday, June 09, 2004 5:12 PM
> To: www-ws-desc@w3.org
> Subject: Sample Application described in WSDL using HTTP binding and
> showing messages
> 
> 
> 
> This is potential primer material that explores how to use 
> the WSDL http binding to describe interactions with an HTTP 
> service.  This is an example of music information and 
> purchasing Web service.  It is styled after the CDDB database 
> http://www.gracenote.com/gn_products/cddb.html and 
> allmusic.com sites.  It has generated a number of questions 
> where I don't think the WSDL as exists can express certain 
> things.  I'm grateful for any reviews or comments on this.  
> It could be put into the primer as well.
> 
> An Artist has:
>  - ID
>  - Name
>  - Biography
>  - Genre
>  - Image
>  - Web site
> 
> Clients have 3 types of interactions: retrieve all/specific 
> information, change/add/delete information, and search based 
> upon a subset of the Artist fields. 
> 
>  - Get Artist complete information for a given Artist
>  - Get Artist field contents (Name, Biography, etc.) for a 
> given Artist
>  - Add Artist
>  - Update Artist
>  - Get Artist list by Artist name, genre
> 
> Schema
> <?xml version="1.0" encoding="UTF-8"?>
> <xs:schema 
> targetNamespace="http://www.w3.org/2002/ws/music/2004/" 
> xmlns:xs="http://www.w3.org/2001/XMLSchema" 
> xmlns:tns="http://www.w3.org/2002/ws/music/2004/" 
> elementFormDefault="qualified" attributeFormDefault="unqualified">
>   <xs:element name="Music">
>     <xs:complexType name="Music">
>       <xs:sequence>
>         <xs:element ref="tns:Artist" maxOccurs="unbounded"/>
>         <xs:element ref="tns:ArtistRef" maxOccurs="unbounded"/>
>         <xs:any namespace="##other" processContents="lax"/>
>       </xs:sequence>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- To do a /Music/Artist/5, need to have a type with only 
> 1 child -->
>   <xs:complexType name="ArtistIDBase">
>     <xs:sequence>
>       <xs:element name="id" type="xs:ID"/>
>     </xs:sequence>
>   </xs:complexType>
>   
>    <!-- When Adding an artist, the ID isn't known -->
>   <xs:element name="ArtistWithoutID">
>     <xs:complexType name="ArtistWithoutId">
>       <xs:sequence>
>         <xs:element name="Name" type="xs:string"/>
>         <xs:element name="Biography" type="xs:string"/>
>         <xs:element name="Genre" type="xs:string"/>
>         <xs:element name="Image" type="xs:anyURI"/>
>         <xs:element name="Site" type="xs:anyURI"/>
>         <xs:any namespace="##other" processContents="lax"/>
>       </xs:sequence>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- Need to have ID + all of the fields for <artist> returns -->
>   <!-- probably better modelling in schema to combine the id 
> with the non-id fields -->
>   <xs:element name="Artist">
>     <xs:complexType name="Artist">
>       <xs:complexContent>
>         <xs:extension base="tns:ArtistIDBase">
>           <xs:sequence>
>             <xs:element name="Name" type="xs:string"/>
>             <xs:element name="Biography" type="xs:string"/>
>             <xs:element name="Genre" type="xs:string"/>
>             <xs:element name="Image" type="xs:anyURI"/>
>             <xs:element name="Site" type="xs:anyURI"/>
>             <xs:any namespace="##other" processContents="lax"/>
>           </xs:sequence>
>         </xs:extension>
>       </xs:complexContent>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- Need a query structure to do queries, ie &name=thieverycorp -->
>    <xs:element name="ArtistQuery">
>     <xs:complexType name="ArtistQuery">
>       <xs:complexContent>
>         <xs:extension base="tns:ArtistIDBase">
>           <xs:sequence>
>             <xs:element name="Name" type="xs:string" minOccurs="0"/>
>             <xs:element name="Genre" type="xs:string" minOccurs="0"/>
>             <xs:element name="Rating" type="xs:decimal" 
> minOccurs="0"/>
>           </xs:sequence>
>         </xs:extension>
>       </xs:complexContent>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- ID + REF structure for getting back list of IDs that 
> can be used to create URI -->
>   <xs:element name="ArtistIDRef">
>     <xs:complexType name="ArtistIDRef">
>       <xs:complexContent>
>         <xs:extension base="tns:ArtistIDBase">
>           <xs:sequence>
>             <xs:element name="Name" type="xs:string"/>
>           </xs:sequence>
>         </xs:extension>
>       </xs:complexContent>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- Artist Field names for doing field queries -->
>   <xs:element name="ArtistIDFieldName" type="tns:ArtistField"/>
>   <xs:complexType name="ArtistField">
>     <xs:complexContent>
>       <xs:extension base="tns:ArtistIDBase">
>         <xs:sequence>
>           <xs:element name="Field" type="tns:ArtistFieldNames"/>
>         </xs:sequence>
>       </xs:extension>
>     </xs:complexContent>
>   </xs:complexType>
>   
>   <!-- Artist Field Name + Value for setting field -->
>   <xs:element name="ArtistFieldNameAndValue">
>     <xs:complexType name="ArtistFieldNameAndValue">
>       <xs:complexContent>
>         <xs:extension base="tns:ArtistField">
>           <xs:sequence>
>             <xs:element name="Value"/>
>           </xs:sequence>
>         </xs:extension>
>       </xs:complexContent>
>     </xs:complexType>
>   </xs:element>
>   
>   <!-- List of field names -->
>   <xs:simpleType name="ArtistFieldNames">
>     <xs:restriction base="xs:string">
>       <xs:enumeration value="Name"/>
>       <xs:enumeration value="Biography"/>
>       <xs:enumeration value="Genre"/>
>       <xs:enumeration value="Image"/>
>       <xs:enumeration value="Site"/>
>     </xs:restriction>
>   </xs:simpleType>
>   
>   <!-- URI for getting back opaque URIs -->
>   <xs:complexType name="uri">
>     <xs:sequence>
>       <xs:element name="uri" type="xs:anyURI"/>
>     </xs:sequence>
>   </xs:complexType>
> </xs:schema>
> 
> 
> 
> Interacting using the x-www-form-uriencoded style
> WSDL
> 
> <?xml version="1.0" encoding="UTF-8"?>
> <wsdl:definitions xmlns:musicw="http://example.com/Artist" 
> xmlns:wsdl="">
> 	<xs:import href="Music-Artist.xsd"/>
> 	<wsdl:interface name="Artist">
> 		<wsdl:operation name="ArtistSearch" method="GET">
> 			<wsdl:input ref="music:ArtistQuery"/>
> 			<wsdl:output ref="music:Music"/>
> 		</wsdl:operation>
> 		<wsdl:operation name="ArtistRefSearch" method="GET">
> 			<wsdl:input ref="music:ArtistQuery"/>
> 			<wsdl:output ref="music:Music"/>
> 		</wsdl:operation>
> 		<wsdl:operation name="GetArtist" method="GET">
> 			<wsdl:input ref="music:ArtistID"/>
> 			<wsdl:output ref="music:Artist"/>
> 		</wsdl:operation>
> 
> 		<!-- Given a uri in a field for an artist, 
> simply dereference the URI -->
> 		<wsdl:operation name="GetArtistOpaqueURI" method="GET">
> 			<wsdl:input ref="music:uri"/>
> 			<wsdl:output ref="music:ArtistWithoutURI"/>
> 		</wsdl:operation>
> 		
> 		<wsdl:operation name="GetFieldByFieldName" method="GET">
> 			<wsdl:input ref="music:ArtistFieldName"/>
> 			<wsdl:output ref="xsd:any"/>
> 		</wsdl:operation>
> 		<wsdl:operation name="AddArtistServerID" method="POST">
> 		   <wsdl:input ref="music:ArtistWithoutID"/>
> 		   <wsdl:output ref="music:ArtistRef"/>
> 		 </wsdl:operation>	 
> 		 <wsdl:operation name="AddArtistClientID" method="POST">
> 		   <wsdl:input ref="music:Artist"/>
> 		   <wsdl:output ref="music:ArtistRef"/>
> 		 </wsdl:operation>
> 		<wsdl:operation name="DeleteArtist" method="DELETE">
> 			<wsdl:input ref="music:ArtistID"/>
> 		</wsdl:operation>
> 		<wsdl:operation name="UpdateArtist" method="PUT">
> 			<wsdl:input ref="music:Artist"/>
> 			<wsdl:output ref="music:Artist"/>
> 		</wsdl:operation>
> 		<wsdl:operation name="UpdateField" method="PUT">
> 			<wsdl:input 
> ref="music:ArtistFieldNameAndValue"/>
> 		</wsdl:operation>
> 
> 	</wsdl:interface>
> 	<wsdl:binding name="Artist" interface="Artist" 
> http:defaultMethod="GET">
> 	<wsdl:operation ref="ArtistSearch" location="Artist/{Name}"/>
> 	<wsdl:operation ref="ArtistRefSearch" 
> location="ArtistRef/{Name}"/>
>   	<wsdl:operation ref="GetArtist" location="Artist/{ID}"/>
>   	<wsdl:operation ref="GetArtistOpaqueURI" location="{uri}"/>
>   	<wsdl:operation ref="GetFieldByFieldname" 
> location="Artist/{ID}/"/>
>   	<wsdl:operation ref="AddArtistServerID" 
> location="Artist" method="POST"/>
>  	<wsdl:operation ref="AddArtistClientID" 
> location="Artist" method="POST"/>
>   	<wsdl:operation ref="DeleteArtist" 
> location="Artist/{ID}" method="DELETE"/>
>   	<wsdl:operation ref="UpdateArtist" 
> location="Artist/{ID}" method="PUT"/>
>   	<wsdl:operation ref="UpdateArtistField" 
> location="Artist/{ID}" method="PUT"/>
> 	</wsdl:binding>
> </wsdl:definitions>
> 
> Message Examples
> 
> Example: ArtistSearch 
> GET /Music/Artist?genre="electronica"
> 
> Return:
> <Music>
>   <Artist>
>     <ID>5</ID>
>     <Name>Thievery Corp</Name> 
>     <Genre>Electronica</Genre>
>     <site>http://thievery.com</site>
>   </Artist>
> </Music>
> 
> Example: GetAllArtists
> GET /Music/Artist
> 
> Returns:
> <Music>
>   <Artist>
>     <ID>5</ID>
>     <Name>Thievery Corp</Name>
>     <Genre>Electronica</Genre>
>     <site>http://thievery.com</site>
>   </Artist>
> </Music>
> 
> Example: GetArtistReferences
> GET /Music/ArtistRef?genre="electronica"
> 
> Return:
> <Music>
>   <ArtistRef>
>     <ID>5</ID>
>     <Name>Thievery Corp</Name> 
>   </ArtistRef>
> </Music>
> 
> Example: GetArtist 
> GET /Music/Artist/5
> 
> Return:
> <Artist>
>   <ID>5</ID>
>   <Name>Thievery Corp</Name>
>   <Genre>Electronica</Genre>
>   <site>http://thievery.com</site>
> </Artist>
> 
> Example: GetArtistOpaqueURI
> * This assumes the URI="id/xyz"
> GET /Music/Artist/id/zyz
> 
> Return:
> <Artist>
>   <Name>Thievery Corp</Name>
>   <Genre>Electronica</Genre>
>   <site>http://thievery.com</site>
> </Artist>
> 
> 
> Example: GetFieldByFieldName
> GET /Music/Artist/5?field="site"
> 
> Return:
> <site>http://thievery.com</site>
> 
> Example: AddArtistServerId
> POST /Music/Artist
> <Artist>
>     <Name>Thievery Corp version 2</Name>
>     <Genre>Electronica</Genre>
>     <site>http://newbetterthievery.com</site>
> </Artist>
> 
> Returns:
> Content-Location: /Music/Artist/6
> * How is the HTTP Content-location mapped to xml in this 
> case?  Is it dropped?  Should there be XML returned?
> 
> Example: AddArtistClientID
> * I don't think this works in the current WSDL http binding
> POST /Music/Artist/7
> <Artist>
>     <ID>7</ID>
>     <Name>Thievery Corp version 3</Name>
>     <Genre>Electronica</Genre>
>     <site>http://newwaybetterthievery.com</site>
> </Artist>
> 
> Returns:
> Content-Location: /Music/Artist/7
> 
> Example: DeleteArtist
> DELETE /Music/Artist/5
> 
> Example: UpdateArtist
> * I don't think this works in the current WSDL http binding
> PUT /Music/Artist/5
> <Artist>
>     <ID>5</ID>
>     <Name>Thievery Corp</Name>
>     <Genre>Electronica</Genre>
>     <site>http://newbetterthievery.com</site>
>   </Artist>
> 
> Example: UpdateArtistField
> * I don't think this works in the wsdl as is
> PUT /Music/Artist/5/site
> <site>http://newbetterthievery.com</site>
> 
>
Received on Tuesday, 22 June 2004 14:55:11 UTC