COMS E6125 Web-enHanced Information Management (WHIM)

1. COMS E6125 Web-enHanced Information Management (WHIM) Prof. Gail Kaiser Spring 2008 Kaiser: COMS E6125

2. Today’s Topic: • Introduction to Web Services (SOAP and WSDL) Kaiser: COMS E6125

3. What Are Web Services? • Any application that programmatically invokes computations via the Web infrastructure could be said to be using “web services” • Includes REST, particularly when using POST forms or when GET includes query (both supplying computational parameters and often implicitly executing computations beyond webpage return) • But historically the term has been used to mean more explicit remote procedure (service) calls Kaiser: COMS E6125

4. Contrast REST with Service-Oriented Architecture (SOA) • SOA existed as distributed objects before the web (e.g., CORBA, DCOM), where services were often treated as object methods • SOA computation proceeds through connections between independent services communicating via remote procedure call (e.g., SOAP over HTTP) • SOA’s rich collection of methods (the services) with relatively limited parameter passing vs. REST’s small number of methods (HTTP) with rich parameter passing (web pages, form data) Kaiser: COMS E6125

5. More REST vs. SOA • REST model increasingly supported by APIs (e.g., yahoo, flikr, facebook, myspace, twitter, amazon) • But most development systems that support REST also support SOAP/RPC [some deprecating] • And most REST APIs “hide” effective RPC in GET URLs or POST forms • Most business applications still use SOA • Some common elements – XML, WSDL (although REST often uses WADL instead, or nothing) Kaiser: COMS E6125

6. Web Services Standards • REST is an architectural style, not a standard (although HTTP is a standard) • Web service standards include • SOAP version 1.2 = Simple Object Access Protocol (W3C), aka Service Oriented Architecture Protocol • WSDL version 2.0 – Web Services Description Language (W3C) • UDDI version 3.0.2 – Universal Description Discovery and Integration (OASIS) [infrequently used] • Various WS-* (from various organizations) Kaiser: COMS E6125

7. Example Web Service http://www.webservicex.net/WS/WSDetails.aspx?WSID=68&CATID=12 Kaiser: COMS E6125

8. Three Parts to Web Services • “Wire” protocols • Data and RPC encodings • Describing what goes on the wire • Schemas for the data, what methods are available • [Sometimes] “Service discovery” • Means of automatically finding web services Kaiser: COMS E6125

9. Steps to Creating and Using a Web Service • Service provider creates a service or application • Service provider defines a corresponding Web Service Description • Service requester is informed (somehow) of the Web Service Description • Service requester writes the client to access the Web Service, using the protocol and input/output parameters specified in its Web Service Description Kaiser: COMS E6125

10. SOAP Wire Protocol • Written in XML • Conceived as the “minimal” possible infrastructure necessary to perform RPC over the Web • Predecessor XML-RPC ~1998 still in use, even more minimal – no developer-defined data types • Defines a mechanism to pass commands and parameters between clients and servers • Independent of the platform, object model and programming language • SOAP messages transported over HTTP are firewall-friendly and relatively easy to debug (XML text rather than binary stream) Kaiser: COMS E6125

11. SOAP Message • “A SOAP message is fundamentally a one-way transmission between SOAP nodes, from a SOAP sender to a SOAP receiver, but SOAP messages are expected to be combined by applications to implement more complex interaction patterns ranging from request/response to multiple, back-and-forth ‘conversational" exchanges.’ W3C SOAP 1.2 Kaiser: COMS E6125

12. SOAP Message Structure • A message is seen as an envelope that contains the data to be sent (+ control) • The envelope has two main parts, header (optional) and body (mandatory) • The header is for infrastructure level data and control • The body is for application level data SOAP Envelope SOAP Header Header subelements SOAP Body Body subelements Kaiser: COMS E6125

13. SOAP Envelope Structure XML namespace that defines SOAP related names <env:Envelope xmlns:env=“http://www.w3.org/2003/05/soap-envelope/ <env:Header> <!-- content of header goes here (optional) --> </env:Header> <env:Body> <!-- content of body goes here (mandatory) --> </env:Body> </env:Envelope> <env:Envelope xmlns:env=“http://www.w3.org/2003/05/soap-envelope/”> <env:Body> <et:eTicket xmlns:et=“http://www.acme-travel.com/eticket/schema”> <et:passengerName first=“John” last=“Doe”/> <et:flightInfo airlineName=“ZZ” flightNumber=“1111” departureDate=“2008-01-01” departureTime=“1234”/> </et:eTicket> </env:Body> </env:Envelope> The XML schema that defines the travel application types

14. HTTP POST SOAP Call SOAP Envelope SOAP Header Header subelements SOAP Body Body subelements POST /travelservice HTTP/1.1 HOST: some.server.com Content-Type: application/soap+xml; charset=“utf-8” Content-Length: nnnn <env:Envelope xmlns:env=“http://www.w3.org/2003/05/soap-envelope/”> <env:Body> <et:eTicket xmlns:et=“http://www.acme-travel.com/eticket/schema”> <et:passengerName first=“John” last=“Doe”/> <et:flightInfo airlineName=“ZZ” flightNumber=“1111” departureDate=“2008-01-01” departureTime=“1234”/> </et:eTicket> </env:Body> </env:Envelope>

15. Request Example POST /travelservice HTTP/1.1 Content-Type: application/soap+xml; charset=“utf-8” Content-Length: nnnn <env:Envelope xmlns:env=“http://www.w3.org/2003/05/soap-envelope/”> <env:Body> <m:GetFlightInfo xmlns:m=“http://www.acme-travel.com/flightinfo” env:encodingStyle=“http://www.w3.org/2003/05/soap-encoding” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance”> <airlineName xsi:type=“xsd:string”>ZZ</airlineName> <flightNumber xsi:type=“xsd:int”>1111</flightNumber> </m:GetFlightInfo> </env:Body> </env:Envelope> Kaiser: COMS E6125

16. Response Example HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=“utf-8” Content-Length: nnnn <env:Envelope xmlns:env=“http://www.w3.org/2003/05/soap-envelope/”> <env:Body> <m:GetFlightInfoResponse xmlns:m=“http://www.acme-travel.com/flightinfo” env:encodingStyle=“http://www.w3.org/2003/05/soap-encoding” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance”> <flightInfo> <gate xsi:type=“xsd:int”>10</gate> <status xsi:type=“xsd:string”>ON TIME</status> </flightInfo> </m:GetFlightInfoResponse> </env:Body> </env:Envelope> Kaiser: COMS E6125

17. Fault Message • If failure, the contents of the SOAP response envelope will generally be a Fault message, along the lines of: <env:Body> <env:Fault> <env:Code> <env:Value>env:Sender</env:Value> <env:Subcode> <env:Value>rpc:BadArguments</env:Value> </env:Subcode> </env:Code> <env:Reason> <env:Text xml:lang="en-US">Processing error</env:Text> </env:Reason> <env:Detail> … </env:Detail> </env:Fault> </env:Body>

18. The SOAP Header • The header is the holder of administrative and control information • Typical uses: transaction identifiers, security certificates, processing instructions for intermediaries • Target of most WS-* specifications Kaiser: COMS E6125

19. SOAP RPC Interaction Style • The applications (sender and receiver) agree upon the method signatures • The body of the SOAP message contains the actual call: the procedure name and the input parameters • The body of a response message contains the output parameters and optional “result” (analogous to return value) Kaiser: COMS E6125

20. Example RPC-style <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" >5</t:transaction> </env:Header> <env:Body> <m:chargeReservation xmlns:m="http://travelcompany.example.org/" env:encodingStyle="http://www.w3.org/2003/05/soap-encoding“> <m:reservation xmlns:m="http://travelcompany.example.org/reservation"> <m:code>FT35ZBQ</m:code> </m:reservation> <o:creditCard xmlns:o="http://mycompany.example.com/financial"> <n:name xmlns:n="http://mycompany.example.com/employees">Gail Kaiser</n:name> <o:number>123456789099999</o:number> <o:expiration>2010-02</o:expiration> </o:creditCard> </m:chargeReservation> </env:Body> </env:Envelope>

21. RPC-style Response <?xml version='1.1' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true">5</t:transaction> </env:Header> <env:Body> <m:chargeReservationResponse env:encodingStyle="http://www.w3.org/2003/05/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <m:code>FT35ZBQ</m:code> <m:viewAt> http://travelcompany.example.org/reservations?code=FT35ZBQ </m:viewAt> </m:chargeReservationResponse> </env:Body> </env:Envelope>

22. RPC-style Response with return value <?xml version='1.1' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true">5</t:transaction> </env:Header> <env:Body> <m:chargeReservationResponse xmlns:m="http://travelcompany.example.org/" env:encodingStyle="http://www.w3.org/2003/05/soap-encoding" xmlns:rpc="http://www.w3.org/2003/05/soap-rpc“> <rpc:result>m:status</rpc:result> <m:status>confirmed</m:status> <m:code>FT35ZBQ</m:code> <m:viewAt> http://travelcompany.example.org/reservations?code=FT35ZBQ </m:viewAt> </m:chargeReservationResponse> </env:Body> </env:Envelope>

23. SOAP Document Interaction Style • The applications agree upon the structure of the documents to be exchanged • The body of a SOAP message contains a document • The response is also a document • Still a form of RPC, but typically processed asynchronously Kaiser: COMS E6125

24. Example Document-style <?xml version='1.1' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2008-02-24T13:20:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>Gail Kaiser</n:name> </n:passenger> </env:Header> <-- cont. -->

25. Example Document-style <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>New York</p:departing> <p:arriving>Los Angeles</p:arriving> <p:departureDate>2008-12-25</p:departureDate> <p:departureTime>late afternoon</p:departureTime> <p:seatPreference>aisle</p:seatPreference> </p:departure> <p:return> <p:departing>Los Angeles</p:departing> <p:arriving>New York</p:arriving> <p:departureDate>2009-01-01</p:departureDate> <p:departureTime>mid-morning</p:departureTime> <p:seatPreference/> </p:return> </p:itinerary> <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels"> <q:preference>none</q:preference> </q:lodging> </env:Body> </env:Envelope>

26. Document-style Response <?xml version='1.1' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2008-02-24T13:35:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>Gail Kaiser</n:name> </n:passenger> </env:Header> <-- cont. -->

27. Document-style Response <env:Body> <p:itineraryClarification xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing> <p:airportChoices> JFK LGA EWR </p:airportChoices> </p:departing> </p:departure> <p:return> <p:arriving> <p:airportChoices> JFK LGA EWR </p:airportChoices> </p:arriving> </p:return> </p:itineraryClarification> </env:Body> </env:Envelope>

28. Response to Response <?xml version='1.1' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <-- as before --> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>EWR</p:departing> </p:departure> <p:return> <p:arriving>EWR</p:arriving> </p:return> </p:itinerary> </env:Body> </env:Envelope>

29. Three Parts to Web Services • “Wire” protocols • Data and RPC encodings • Describing what goes on the wire • Schemas for the data, what methods are available • [Sometimes] “Service discovery” • Means of automatically finding web services Kaiser: COMS E6125

30. Steps to Creating and Using a Web Service • Service provider creates a service or application • Service provider defines a corresponding Web Service Description • Service requester is informed (somehow) of the Web Service Description • Service requester writes the client to access the Web Service, using the protocol and input/output parameters specified in its Web Service Description Kaiser: COMS E6125

31. Purposes of Web Service Description • Defines a contract that the web service implements - the client exchanges messages based on this contract • Used by tools to generate proper stubs - ensure that the stubs implement the expected behavior for the client Kaiser: COMS E6125

32. WSDL = Web Services Description Language • Written in XML • Metadata language of Web Services • Used to define an individual Web service • The operations offered by the service (what) • The mechanisms to access the service (how) • The location at which the service is made available (where) Kaiser: COMS E6125

33. WSDL • Can be used to design specifications to invoke and operate Web Services on the Internet and to access and invoke remote applications and databases • Extensible to allow the description of endpoints and their messages, regardless of what message formats or network protocols are used for communicating • If you want to create an application that communicates with a particular Web Service, in principle all you need is that service's WSDL file (although would also be nice to know what the Web Service does - there’s an optional wsdl:document element for human readable documentation)

34. WSDL Structure • Abstract part: operations, messages sent and received as operation inputs and outputs, types of data to be exchanged • Concrete part: binding to transport and wire format details that users must follow to access the service, endpoint network address WSDL specification abstract part types messages port types & operations <definitions name=“ServiceName”> <types> data types used... </types> <message> parameters used... </message> <portType> set of operations performed... </portType> <binding> communication protocols and data formats used... </binding> <service> set of ports to service provider endpoints </service> </definitions> concrete part bindings services & ports

35. WSDL Types • <types> element defines the data types that are used by the web service and exchanged in messages • By default uses XML Schema syntax to define data types <types> <complexType name="CompanyInfo"/> <element name="CompanyName" type="xsd:string"/> <element name="Address" type="xsd:string"/> </complexType> <complexType name="ReimbursementRequest"/> <element name="amount" type="xsd:float"/> <element name="date=" type="xsd:string"/> </complexType> ... </types>

36. WSDL Messages • <message> element defines the data elements of an operation • Each message can consist of one or more parts and zero or more attachments • Each part must have a name and a type • The parts are analogous to the parameters of a function call in a traditional programming language <types> ... </types> <message name="ReimbursementRequestInput"> <part name="employeeId" type="xsd:string"/> <part name="info" type="ReimbursementRequest"/> <attachment name="hotelReceipt" uri="uri to image of hotel receipt"/> <attachment name="carRentalReceipt" uri="uri to image of rental car receipt"/> </message>

37. WSDL Port Types • <portType> element defines the actual operations that can be performed and the messages (parameters) that are involved • Can be compared to a function library (or a module or a class) in a traditional programming language <portType name=“anyname”> <operation name="Reimburse"> <input message="ReimbursementRequestInput"/> </operation> <operation> ... </operation> <operation> ... </operation> <operation> ... </operation> ... </portType>

38. Types of Port Operations • Each operation represents a message exchange pattern the Web service supports • Syntactically, operation is a combination of input and output or fault messages indicating what role a message plays in the interaction • One-way: The operation can receive a message but will not return a response (asynchronous) • Notification: The operation can send a message but will not wait for a response (asynchronous) • Request-response: The operation can receive a request and will return a response (synchronous) • Solicit-response: The operation can send a request and will wait for a response (synchronous) Kaiser: COMS E6125

39. One-Way <wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken"><wsdl:input name="nmtoken"? message="qname"/></wsdl:operation> </wsdl:portType > </wsdl:definitions> • The input element specifies the abstract message format for the one-way operation Kaiser: COMS E6125

40. Notification <wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken"> <wsdl:output name="nmtoken"? message="qname"/> </wsdl:operation> </wsdl:portType > </wsdl:definitions> • The output element specifies the abstract message format for the notification operation Kaiser: COMS E6125

41. Request-Response <wsdl:definitions ... ><wsdl:portType ... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType> </wsdl:definitions> • The input and output elements specify the abstract message format for the request and response, respectively • The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation

42. Solicit-Response <wsdl:definitions ... ><wsdl:portType ... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType> </wsdl:definitions> • The output and input elements specify the abstract message format for the solicited request and response, respectively • The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation Kaiser: COMS E6125

43. WSDL Abstract Elements <definitions name=“NameofWebService” add here XML namespaces fixsd and eticketnamespaces > <types> include here types used </types> <message name=“GetFlightInfoInput”> <part name=“airlineName” type=“xsd:string”/> <part name=“flightNumber” type=“xsd:int”/> </message> <message name=“GetFlightInfoOutput”> <part name=“flightInfo” type=“fixsd:FlightInfoType”/> </message> <message name=“CheckInInput”> <part name=“body” element=“eticketxsd:Ticket”/> </message> <portType name=“AirportServicePortType”> <operation name=“GetFlightInfo”> <input message=“tns:GetFlightInfoInput”/> <output message=“tns:GetFlightInfoOutput”/> </operation> <operation name=“CheckIn”><input message=“tns:CheckInInput”/> </operation> </portType> </definitions>

44. WSDL Example http://www.webservicex.net/WS/WSDetails.aspx?WSID=68&CATID=12 Kaiser: COMS E6125

45. WSDL Concrete Elements • Binding the interface to a transport protocol - What communication protocol to use to transport service requests and responses (e.g., SOAP over HTTP or HTTPS) • The service as a collection of all bindings of the same interface - How to accomplish individual service interactions over this protocol (the interface in its all available implementations) • The endpoint or network address of the binding - Where to terminate communication (i.e., the network address of the service provider) Kaiser: COMS E6125

46. Binding, Service and Port Elements • <binding> element defines the message format and protocol details for each port - how a given interaction occurs over the specified protocol • The communication protocol • The message encoding (literal or SOAP-encoding) • Interaction style (RCP-style or document-style) for all operations/messages defined in a given portType • <service> element groups a set of port elements • <port> element provides the “where”: a single end point as a combination of a binding and a network address (URL) Kaiser: COMS E6125

47. Binding to SOAP • binding element has two attributes • name attribute (any name you want) defines the name of the binding • type attribute points to the port for the binding • soap:binding element has two attributes • style attribute can be "rpc" or "document“ • transport attribute defines the SOAP protocol to use, e.g., HTTP, SMTP Kaiser: COMS E6125

48. Binding to SOAP • operation element defines each operation that the port exposes • For each operation the corresponding SOAP action has to be defined • Also specify whether the input and output are “encoded” (give URL for abstract type definitions) or "literal“ (using XML Schema types) Kaiser: COMS E6125

49. Example SOAP Binding <binding name=“AirportServiceSoapBinding” type=“tns:AirportServicePortType”> <soap:binding transport=“http://www.w3.org/2003/05/soap/bindings/HTTP”/> <operation name=“GetFlightInfo”> <soap:operation style=“rpc” soapAction=“http://acme-travel/flightinfo”/> <input> <soap:body use=“encoded” namespace=“http://acme-travel.com/flightinfo” encodingStyle=“http://www.w3.org/2003/05/soap-encoding”/> </input> <output> <soap:body use=“encoded” namespace=“http://acme-travel.com/flightinfo” encodingStyle=“http://www.w3.org/2003/05/soap-encoding”/> </output> </operation> <operation name=“CheckIn”> <soap:operation style=“document” soapAction=“http://acme-travel.com/checkin”/> <input> <soap:body use=“literal”/> </input> </operation> </binding> <service name=“travelservice”> <port name=“travelservicePort” binding=“tns:AirportServiceSoapBinding”> <soap:address location=“http://acme-travel.com/travelservice”/> </port> </service>

50. Another Web Service Example • http://www.webservicex.net/WCF/ServiceDetails.aspx?SID=22 Kaiser: COMS E6125