Describing Web Services An Overview of WSDL

CS595G: Web Services and Security 1/17/2006 Marco Cova marco@cs.ucsb.edu Describing Web Services An Overview of WSDL

Outline • Motivations • WSDL specification and an example • Tools • WSDL alternatives

Web Services Interaction Typical steps in WS interaction: • Discovery: the requester entity becomes aware of the provider entity either by directly knowing the provider agent's address or through some discovery service • Agreement on service description: provider and requester agent “agree” on the service description • Agents setup: web service description and semantics are input to requester and provider agents • Messages are exchanged between the requester and provider agents

Web Services Stack Here, we will focus on the service description layer and WSDL specifically Image taken from http://www.oracle.com/technology/oramag/webcolumns/2003/techarticles/images/smith_wsc_f1.gif

Web Services description: goals and requirements • To provide a structured, formal description of a web service: • What operations are available and how to invoke them • To describe how to concretely access a web service: • Web service address • Transport protocol • What type of description: syntactical or semantic?

WSDL • Web Service Definition Language: a language to describe web services • XML-based Status: • WSDL 1.1 is a W3C note published on 15 March 2001 • WSDL 2.0 is a W3C Candidate Recommendation (last update on 6 January 2006)

WSDL goals • Service description: documentation for distributed systems • Language- and platform-independent • Service automation: recipe for automating the details involved in the service invocation

WSDL: web service model A WSDL document defines a web services as • Collection of communicating endpoints capable of exchanging messages For each web service, WSDL may provide two types of definitions: • Abstract: the web service is seen as a language- and platform-independent interface • Concrete: the web service is seen as a component accessible through specific transport and network standards

WSDL elements Main WSDL elements: • Types: container for data type definitions using some type system, typically XML Schema • Message: an abstract, typed definition of the data being communicated • Operation: an abstract description of an action supported by the service • Port Type: an abstract set of operations supported by one or more endpoints • Binding: a concrete protocol and data format specification for a particular port type • Port: a single endpoint defined as a combination of a binding and a network address • Service: a collection of related endpoints

WSDL elements – cnt'd For each part of the specification, an example taken from the Amazon E-Commerce Service is presented. The full WSDL document is located at http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl

wsdl:types <definitions .... > <types> <-- type-system extensibility element --> * </types> </definitions> • Data type definitions needed to define the exchanged messages • By default, the types are defined in terms of XML Schema

wsdl:types - example <types> ... <xs:element name="ItemSearch"> <xs:complexType><xs:sequence> <xs:element name="SubscriptionId" type="xs:string" minOccurs="0"/> <xs:element name="AWSAccessKeyId" type="xs:string" minOccurs="0"/> <xs:element name="AssociateTag" type="xs:string" minOccurs="0"/> <xs:element name="XMLEscaping" type="xs:string" minOccurs="0"/> <xs:element name="Validate" type="xs:string" minOccurs="0"/> <xs:element name="Shared" type="tns:ItemSearchRequest" minOccurs="0"/> <xs:element name="Request" type="tns:ItemSearchRequest" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType></xs:element> ... </types>

wsdl:message • Messages exchanged to provide a service • Messages are simply containers of parts which are defined in terms of the types described in the types section <definitions .... > <message name="nmtoken"> * <part name="nmtoken" element="qname"? type="qname"?/> * </message> </definitions>

wsdl:message - example <message name="ItemSearchRequestMsg"> <part name="body" element="tns:ItemSearch"/> </message> <message name="ItemSearchResponseMsg"> <part name="body" element="tns:ItemSearchResponse"/> </message>

wsdl:portType <wsdl:definitions .... > <wsdl:portType name="nmtoken"> <wsdl:operation name="nmtoken" .... /> * </wsdl:portType> </wsdl:definitions> • A portType is a named set of abstract operations and the abstract messages involved

Message exchange patterns 4 messaging types: • One-way: endpoint receives a message • Request-response: endpoint receives a message, and sends a correlated message • Solicit-response: endpoint sends a message, and receives a correlated message. • Notification: endpoint sends a message

wsdl:portType - example <portType name="AWSECommerceServicePortType"> ... <operation name="ItemSearch"> <input message="tns:ItemSearchRequestMsg"/> <output message="tns:ItemSearchResponseMsg"/> </operation> ... </portType> In addition, a message can be used to communicate a fault: <fault message=”...”/>

wsdl:binding <wsdl:definitions .... > <wsdl:binding name="nmtoken" type="qname"> * <-- extensibility element (1) --> * <wsdl:operation name="nmtoken"> * <-- extensibility element (2) --> * <wsdl:input name="nmtoken"? > ? <-- extensibility element (3) --> </wsdl:input> <wsdl:output name="nmtoken"? > ? <-- extensibility element (4) --> * </wsdl:output> <wsdl:fault name="nmtoken"> * <-- extensibility element (5) --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> </wsdl:definitions> • Message format and protocol details for operations and messages defined by a portType

wsdl:binding – cnt'd • Extensibility elements allow to specify • Concrete grammar for input, output and fault messages • Concrete per-binding information • Concrete per-operation information • The WSDL specification introduces binding extensions for: • SOAP • HTTP GET/POST • MIME

wsdl:binding - example <binding name="AWSECommerceServiceBinding" type="tns:AWSECommerceServicePortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> ... <operation name="ItemSearch"> <soap:operation soapAction="http://soap.amazon.com"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> ... </binding>

wsdl:port <wsdl:definitions .... > <wsdl:service .... > * <wsdl:port name="nmtoken" binding="qname"> * <-- extensibility element (1) --> </wsdl:port> </wsdl:service> </wsdl:definitions> • Defines an individual endpoint by specifying an address for a binding

wsdl:port - example <service name="AWSECommerceService"> <port name="AWSECommerceServicePort" binding="tns:AWSECommerceServiceBinding"> <soap:address location="http://soap.amazon.com/onca/soap?Service=AWSECommerceService"/> </port> </service>

wsdl:service <wsdl:definitions .... > <wsdl:service name="nmtoken"> * <wsdl:port .... />* </wsdl:service> </wsdl:definitions> • A service simply groups related ports together

Tools: editor How do you write WSDL files? • By hand: some editors have special support for WSDL • Don't write them: automatic generation (in a few slides)

Tools: validation • WSDL documents can be quite large (the Amazon E-Commerce Service WSDL document is 2432 lines of code and over 100KB) • Tools to validate/analyze WSDL documents: • http://xmethods.net/ve2/Tools.po • http://www.softwaresecretweapons.com/jspwiki/services/oy-lm-1.3/generator.jsp

Tools: WSDL generation and client generation • Manually creating a WSDL file for a web service is a difficult and error-prone task • Given a WSDL file, generating a client to interact with the service is a repetitive task • There exist toolkits for all major languages that allow to automate both tasks

WSDL toolkit: Java • Axis: http://ws.apache.org/axis/ • Builds stubs, skeleton and data types from WSDL • java org.apache.axis.wsdl.WSDL2Java AWSECommerceService.wsdl • Builds WSDL from Java code • java org.apache.axis.wsdl.Java2WSDL -o wp.wsdl -l "http://localhost:8080/axis/services/WidgetPrice -n"urn:Example6" -p"samples.userguide.example6" "urn:Example6" samples.userguide.example6.WidgetPrice • Axis2: http://ws.apache.org/axis2/

WSDL toolkit: Python • SOAPpy: http://pywebsvcs.sourceforge.net/ • Parsing a WSDL file: >>> from SOAPpy import WSDL >>> wsdlFile = 'http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl' >>> server = WSDL.Proxy(wsdlFile) >>> server.methods.keys() [u'SellerListingSearch', u'CartCreate', u'SellerLookup', u'Help', u'TransactionLookup', u'CartAdd', u'ItemLookup', u'MultiOperation', u'SimilarityLookup', u'CartClear', u'ListLookup', u'CartModify', u'CustomerContentLookup', u'ListSearch', u'BrowseNodeLookup', u'CartGet', u'SellerListingLookup', u'CustomerContentSearch', u'ItemSearch']

WSDL toolkit: Python – cnt'd >>> itemSearchM = server.methods['ItemSearch'] >>> for inparams in itemSearchM.inparams: ... print inparams.name, inparams.type ... body (u'http://webservices.amazon.com/AWSECommerceService/2005-10-05', u'ItemSearch') >>> >>> for outparams in itemSearchM.outparams: ... print outparams.name, outparams.type ... body (u'http://webservices.amazon.com/AWSECommerceService/2005-10-05', u'ItemSearchResponse') >>> result = server.ItemSearch({'body': {'SubscriptionId': 'xxxxxxxxxxxxxxxxxxxx', 'SearchIndex': 'Books', 'Request' : {'SearchIndex': 'Books', 'Title': 'restaurant end universe'}}}) >>> result.Items.TotalPages 2 >>> result['Items'].TotalResults '18'

WSDL toolkit: Python – cnt'd >>> result.Items.Item[0] <SOAPpy.Types.structType Item at -1214384084>: {'ItemAttributes': <SOAPpy.Types.structType ItemAttributes at -1214386100>: {'Title': 'The Restaurant at the End of the Universe', 'ProductGroup': 'Book', 'Author': 'Douglas Adams'}, 'ASIN': '0345391810', 'DetailPageURL': 'http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=sp1%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=0345391810%2526tag=ws%2526lcode=sp1%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/0345391810%25253FSubscriptionId=xxxxxxxxxxxxxxxxxxxx'}

Lessons learned • Working with complex types is... complex and not very interoperable • Editing WSDL files by hand is masochistic. Avoid it as much as you can • If everything seems fine but nothing works, double check your namespaces

Alternatives • At the moment, WSDL 1.1 is “the” web service description language • WSDL 2.0 redefines and cleans up the grammar specified by WSDL • Simplify the XSD, SOAP/REST, WSDL stack: SSDL (SOAP Service Description Language), RESEDEL (REstful SErvices DEscription Language), WRDL (Web Resource Description Language), WADL (Web Application Description Language), SMEX-D (Simple Message EXchange Descriptor), WDL (Web Description Language) • Add semantics description of a service: WSDL-S, WSML (Web Service Modeling Language)

End • Questions?

Describing Web Services An Overview of WSDL