1. SOAP & WSDL Aug’10 – Dec ’10

2. Introduction  SOAP - Simple Object Access protocol Protocol specification for exchanging structured information in the implementation of web services in computer networks  WSDL – Web Services Description Language Provides a way of describing where and how to make requests to a SOAP-based service  Chapter includes ❑ Why SOAP can provide more flexibility than previous RPC protocols ❑ How to format SOAP messages ❑ When to use GET versus POST in an HTTP request ❑ What SOAP intermediaries are ❑ How to describe a service using WSDL Aug’10 – Dec ’10

3. What is SOAP?   A lightweight protocol for exchange of information in a decentralized, distributed environment.   It is a standard way to send information from one computer to another using XML to represent the information.   The SOAP recommendation defines a protocol whereby all information sent from computer to computer is marked up in XML, with the information transmitted via HTTP in most cases. Aug’10 – Dec ’10

4. Advantages of SOAP over other protocols   It’s platform-, language-, and vendor-neutral—Because SOAP is implemented using XML and (usually) HTTP, it is easy to process and send SOAP requests in any language, on any platform   It’s easy to implement—SOAP was designed to be less complex than the other protocols. A SOAP server can be implemented using nothing more than a web server and an ASP page or a CGI script. ❑ It’s firewall-safe—Assuming that you use HTTP as your network protocol, you can pass SOAP messages across a firewall without having to perform extensive configuration. Aug’10 – Dec ’10

5. Creating an RPC server in ASP ❑ To create an RPC server that receives a request and sends back a response ❑ Create an ASP.NET page that accepts two integers and returns the results in XML Values sent : unit price, quantity Values Receives : Discount, Total price ❑ Not a full fledged SOAP service, but has similar architecture Aug’10 – Dec ’10

6. Creating an RPC server in ASP http://localhost:1698/BasicOrderService/GetTotal.aspx?unitprice=8. 5&quantity=6 Aug’10 – Dec ’10

7. Creating an RPC server in ASP http://localhost:1698/BasicOrderService/GetTotal.aspx?unitprice=8. 5&quantity=x Aug’10 – Dec ’10

8. Creating an RPC server in ASP ASP.NET page isn’t limited to being called from a browser Can load the XML directly and then retrieve the numbers from it Sub Main() Dim xdDoc As System.Xml.XmlDocument = new System.Xml.XmlDocument() xdDoc.Load (“http://localhost/BasicOrderService/gettotal.aspx?unitprice=8.5&q uantity=6”) If xdDoc.documentElement.name = “Error” Then MsgBox (“Unable to perform calculation”) Else MsgBox (xdDoc.selectSingleNode(“/*/TotalPrice”).InnerText) End If End Sub Aug’10 – Dec ’10

9. Why not REST?  Sends a URL and receives an XML  Even though the result is XML, it doesn’t conform to the structure of a SOAP message  Also while sending message is not sent as XML, but as URL  But in some cases, request data is difficult or impossible to provide as URL  In such cases, SOAP is better to use, more standardized Aug’10 – Dec ’10

10. Basic SOAP Messages  SOAP messages are basically XML documents, usually sent across HTTP.  SOAP specifies the following: ❑ Rules regarding how the message should be sent ❑ The overall structure of the XML that is sent. This is called the envelope. Any information to be sent over SOAP is contained within this envelope, and is known as the payload. ❑ Rules regarding how data is represented in this XML. These are called the encoding rules. Aug’10 – Dec ’10

11. SOAP Component HTTP Headers SOAP method name SOAP Envelope SOAP Header SOAP Body Call element Object Endpoint ID Method/Interface ID Extension Headers Parameter Data

13. Basic SOAP Messages  When data is sent to a SOAP server, the data must be represented in a way so that the server can understand it. The basic structure of SOAP message is as follows: <head-ns:someHeaderElem xmlns:head-ns=”some URI” env:mustUnderstand=”true{{vert}false” env:relay=”true{{vert}false” env:role=”some URI”/> Specified values Specified values Aug’10 – Dec ’10

14. Basic SOAP Messages English text Texte francais Three Main Elements :,, Three Main Elements :,, and are mandatory, optional and are mandatory, optional and its child elements are only required when an error occurs and its child elements are only required when an error occurs All of the attributes, encodingStyle, mustUnderstand etc are optional Aug’10 – Dec ’10

15. Basic SOAP Messages <Envelope>  Provides the root element for the XML document  namespace : www.w3.org/2003/05/soapenvelope  Includes namespace declarations <soap:Header></soap:Header><soap:Body> IBM IBM </soap:Body></soap:Envelope> Aug’10 – Dec ’10

16. Basic SOAP Messages <Body>  Contains the main body of the SOAP message  Actual RPC calls are made using the direct children of the element THX1138 ZIBKA 3 34.97 Aug’10 – Dec ’10

17. Basic SOAP Messages <Body>  RPC call to a procedure AddToCart in the http://www.wiley.com/soap/ordersystem namespace http://www.wiley.com/soap/ordersystem  Can add multiple calls in a single namespace  The AddToCart procedure takes four parameters: CartId, Item, Quantity, and TotalPrice.  Direct child elements of the element must reside in a namespace other than the SOAP namespace.  This namespace is what the SOAP server uses to uniquely identify this procedure so that it knows what code to run.  When the procedure is done running, the server uses the HTTP response to send back a SOAP message. Aug’10 – Dec ’10

18. Basic SOAP Messages <Body>  The response is another SOAP message, using an XML structure similar to the request THX1138 OK 3 ZIBKA Aug’10 – Dec ’10

19. Basic SOAP Messages <Body> Encoding Style  Refers to the way in which data is represented  Eg: SOAP style encoding, RDF (Resource Description Framework) THX1138 OK 3 ZIBKA Aug’10 – Dec ’10

20. Basic SOAP Messages <Header>  Included when additional information is to be added to the SOAP message  Contains information about the payload  Header blocks are specifically designed for meta information  When a element is used, it must be the first child of the element  Also defines optional attributes, mustUnderstand, role and relay  Eg: Can use a SOAP header for authentication information, so that only authorized person or systems can use the system Aug’10 – Dec ’10

21. Basic SOAP Messages <Header> The mustUnderstand attribute  Specifies if it is necessary for the SOAP server to process a particular header block  A value of true indicates that the header entry is mandatory and the server must either process it or indicate an error User ID goes here... Password goes here... Info goes here... Info goes here... Aug’10 – Dec ’10

22. Basic SOAP Messages <Header> The mustUnderstand attribute  A value of true in header means the server should process the header  If the server doesn’t understand the header, it rejects the entire SOAP message; server is not allowed to process the body  A value of false for mustUnderstand attribute makes the header entry optional  Even if the server doesn’t understand the header, it can process the body  If the mustUnderstand attribute is omitted, it takes the value false, and header entry is optional Aug’10 – Dec ’10

23. Basic SOAP Messages <Header> The role attribute  In some cases a SOAP message may pass through a number of applications on a number of computers before it arrives at its final destination  These are called intermediaries  Using the role attribute, it can be specified that some SOAP headers must be processed by a specific intermediary. The value of the attribute is a URI, which uniquely identifies each intermediary.  When an intermediary processes a header entry, it must remove that header from the message before passing it on.  The SOAP specification also says that a similar header entry can be inserted in its place Aug’10 – Dec ’10

24. Basic SOAP Messages <Header> The role attribute  The SOAP specification defines three roles: ❑ http://www.w3.org/2003/05/soap-envelope/role/next applies to the next intermediary in line, wherever it is. ❑ http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver only applies to the very last stop. ❑ http://www.w3.org/2003/05/soap-envelope/role/none effectively “turns off” the header block Aug’10 – Dec ’10

25. Basic SOAP Messages <Header> The relay attribute  The SOAP specification requires a SOAP intermediary to remove any headers it doesn’t process  By setting the relay attribute to true, you can instruct any intermediary that encounters it to either process it or leave it alone.  If the intermediary does process the header, the intermediary must remove it.  The default value for the relay attribute is false. Aug’10 – Dec ’10

26. Basic SOAP Messages <Fault>  There may be times when a SOAP server is unable to process a SOAP message, for some reasons.  Sometimes a resource needed to perform the operation isn’t available, or invalid parameters were passed, or the server doesn’t understand the SOAP request in the first place.  In these cases, the server returns fault codes to the client to indicate errors.  Fault codes are sent using the same format as other SOAP messages. However, in this case, the element has only one child, a element.  Children of the element contain details of the error. Aug’10 – Dec ’10

27. Basic SOAP Messages <Fault>  A SOAP message indicating a fault might look like this : <soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope” xmlns:rpc=”http://www.w3.org/2003/05/soap-rpc”> soap:Sender rpc:BadArguments Processing error Erreur de traitement WA872 Cart doesn’t exist Aug’10 – Dec ’10

28. Basic SOAP Messages <Fault>  The element contains a consisting of a unique identifier that identifies the type of error Fault CodeDescription VersionMismatchA SOAP message was received that specified a version of the SOAP protocol that this server doesn’t understand. MustUnderstandThe SOAP message contained a mandatory header that the SOAP server didn't understand SenderMessage was not properly formatted, the client made a mistake when creating the SOAP message, or the message contained incorrect information ReceiverIndicates server had problems processing the message even though the contents of the message was formatted properly DataEncodingUnknownIndicates data in the message is organized, or encoded in a way the server doesn’t understand Aug’10 – Dec ’10

29. Defining Web Services  To use a web service, two things are to be known  How to call the service  What to expect as a response from the service  WSDL or Web Service Description Language provides a standardized way to describe a web service  If a WSDL file describing the web service is created and the file is made available, the web service can be used easily  Most toolkits used for creating SOAP messages, can automatically generate a client for the web service by analyzing the WSDL file  In this way, WSDL helps make web services truly platform- and language-independent Aug’10 – Dec ’10

30. WSDL WSDL was developed by IBM,Microsoft and Ariba to describe web services for SOAP toolkit WSDL document outlines what messages the SOAP server expects in order to provide services as well as what messages it returns A client program connecting to a web service can read the WSDL file to determine what operations are available on the server. The client can then use SOAP to actually call one of the operations listed in the WSDL file Aug’10 – Dec ’10

31. WSDL A WSDL file is written in XML, describing the data to be passed and the method for passing it, but it doesn’t lean toward any particular language. That means a web services client generator can use the WSDL information to generate a client in any language. A developer writing an application around it doesn’t have to know the details of the service, just the methods of the proxy class that actually accesses the service. The proxy sits between the client and the actual service, translating messages back and forth. Aug’10 – Dec ’10

32. WSDL <definitions>  A WSDL file starts with a element <definitions name=”temperature” targetNamespace=”http://www.example.com/temperature” xmlns:typens=”http://www.example.com/temperature” xmlns:xsd=”http://www.w3.org/2000/10/XMLSchema” xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns=”http://schemas.xmlsoap.org/wsdl/”>  Defines the name of the web service  Root element in WSDL file  A WSDL file builds the service up in levels. First, it defines the data to be sent and received, and then it uses that data to define messages. Aug’10 – Dec ’10

33. WSDL<types>  A WSDL allows to define the information set using XML Schemas  Eg: Web service that takes postal code and date and returns temperature; the service would have two types of data to deal with <xsd:schema xmlns=”” xmlns:xsd=”http://www.w3.org/2000/10/XMLSchema” targetNamespace=”http://www.example.com/temperature”> Aug’10 – Dec ’10

34. WSDL<messages>  Defines the content of the SOAP message  Defines what the message is, what it is called, and what kind of data it holds Message that consists of an element called getTemperature of the type temperatureRequestType. This translates into the SOAP message: {{it{POSTAL} CODE} {{it{DATE}} Aug’10 – Dec ’10

35. WSDL <portTypes>  Contains a number of portType elements that describe the individual operation provided by the service.  These operations come in two varieties, input and output, and are made up of the messages defined earlier  portType shows it is a request-response pattern  The user sends an input message, the structure of which is defined as a TemperatureRequestMsg, and the service returns an output message in the form of a TemperatureResponseMsg.  In WSDL 2.0, element is changes to element  Interfaces can be extended, which allows inheritance Aug’10 – Dec ’10

36. WSDL <binding>  To bind the operations to the protocol used to send the messages  Process of binding operations to SOAP is as follows : <soap:body use=”encoded” encodingStyle=”http://www.w3.org/2003/05/soap-encoding” namespace=”http://www.example.com/temperature” /> <soap:body use=”encoded” encodingStyle=”http://www.w3.org/2003/05/soap-encoding” namespace=”http://www.example.com/temperature” /> Aug’10 – Dec ’10

37. WSDL <binding><soap:binding>  Specifies it is a SOAP message  transport attribute specifies message is sent via HTTP  style attribute has two possible values : rpc and document  The rpc value is a message with method name and parameters 34652 2004-05-23 Aug’10 – Dec ’10

38. WSDL <binding><soap:binding>  When document style is used, the entire contents of element is considered to be data 34652 2004-05-23 Aug’10 – Dec ’10

39. WSDL <binding><soap:operation>   The SOAP 1.1 specification required all services to use a SOAPAction header defining the application that was supposed to execute it. POST /soap.asp HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Accept-Language: en-us Content-Type: application/x-www-form-urlencoded Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: www.example.com Content-Length: 242 SOAPAction: “http://www.example.org/soap/TemperatureService.asp” 34652 2004-05-23   The SOAP 1.2 specification did away with SOAPAction header, but it is necessary to specify that it is a SOAP message, so element is used Aug’10 – Dec ’10

40. WSDL <binding><soap:body>   The element references an operation   Within the element, how messages are to be presented is defined using the element <soap:body use=”encoded” encodingStyle=”http://www.w3.org/2003/05/soap-encoding” namespace=”http://www.example.com/temperature” />   The use attribute has two possible values : literal and encoded   When use is literal, it means the server is not to assume any particular meaning in the XML   If use is specified as encoded, encodingStyle has to be specified   namespace attribute to specify the namespace of the payload Aug’10 – Dec ’10

41. WSDL <service>   The final step in creating a WSDL file is to specify the service created   binding attribute to refer to the binding created   location attribute in soap:address to specify the address to send the SOAP message Aug’10 – Dec ’10