RE: Sample Application described in WSDL using HTTP binding and showing messages

awesome review.  Comments inline.

> -----Original Message-----
> From: Asir Vedamuthu [mailto:asirv@webmethods.com]
> Sent: Tuesday, June 22, 2004 11:53 AM
> To: David Orchard; www-ws-desc@w3.org
> Subject: RE: Sample Application described in WSDL using HTTP 
> binding and
> showing messages
> 
> 
> 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?

If I am creating an HTTP based web service, would I use WSDL 2.0 HTTP binding or some other description format (text?) for describing my service?  In my mind, I don't see this adding much value for an Amazon/Atom/some other service because of the complexity and lack of re-use of the schema constructs.  For example, we have to create a "GET/PUT/POST/DELETE" operation for interactions with each level of the hierarchy, ie Artist, Album, Artist properties, Album properties.  I would have thought we could have some way of more simply saying "I've got a structure of Artists + props, Albums + props, and they are completely RESTFUL, which means you can do GET/PUT/POST/DELETE on various nodes in the tree".  But this is just my personal observation.

> 
> 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.

Are suggesting that we should change it to say that the target namespace MUST be ignored?  Or that my example is broken?

I did suggest a # of mechanisms for how to serialize a QName into a URI...

> 
> 
> (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.
> 

I'm not sure what you are suggesting.  I think roughly we are trying to define a mechanism for serializing a subset of the contents of a simpleType into a URI.

> 
> (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.
> 

See above.  I think we are trying to make sure we don't have to serialize a namespace name into a URI.  I think we could come up with a standardized Qname to URI binding, or a parameterized QName to URI binding with one such binding defined.

> 
> 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/ArtistWSDL2uriform
> encoding.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 16:14:46 UTC