23.1. Web Services Description Language If I agree to provide you with some XML documents, we will also agree on the document type. That agreement is usually recorded formally in a DTD or schema definition. The definition is like a recipe: It lists the ingredients of a dish – in this case, the data elements of the documents that I'm serving. If I agree to provide you information through an XML-based protocol, you'll want to know the offerings I have available and how to request each one. For this you'll need a description of my service, which I can express formally using the Web Services Description Language (WSDL). The service description is like a menu from a take-out restaurant: It tells you in great detail what is available and your options for getting it. Figure 23-1 shows the components of WSDL in the form of a stack. Ignore the details for now; just focus on the middle column. Figure 23-1. The WSDL stack 
23.1.1 Starting at the top: service WSDL is a layered specification. Each layer depends upon the layer directly below it. There is a certain elegance to layered designs. When you are working with them, you can concentrate on one layer at a time. Using this technique, let's explore WSDL by working from the top down with an application example. Logically enough for a language that describes Web services, the top concept is the service. In our case, it is a global meteorological service offered to subscriber corporations. It might, in turn, get its information from other Web services run by national meteorological departments. 23.1.2 Dividing up work: port A service could offer multiple functions, called operations. To balance the resources for supporting them, the service could span multiple physical computer systems. Access to particular groups of operations is provided by ports. Each port could exist on a different machine or multiple ports could be on the same machine. That is totally up to the Web service creator. Each port has a name. Perhaps one port would serve the temperatures, another the humidity and a third the barometric pressure. It would all depend on what was most convenient for the person constructing the service. Let's call our ports temperature, humidity and pressure. They might have Web addresses such as: -
http://temperature.weatherworld.com/ -
http://humidity.weatherworld.com/ and -
http://pressure.weatherworld.com We could have put two ports on the same machine if that was convenient. Because ports are URL-specific, it makes no sense for this part of a Web service to be defined in an industry standard, as you might define an industry-standard DTD or schema. The other parts of a WSDL definition are more reusable than the ports. 23.1.3 Choosing a transport protocol: binding Now that we know where on the Internet to go for the ports that give access to different operations of the service, we need to know how to communicate with them. For that, each port must specify a binding. Protocols tend to build on one another. A binding is basically a way of defining a new protocol based on an existing one. In this case, the existing protocol is the transport protocol that is used to transport the messages from place to place. It makes sense to build on top of an existing transport protocol because otherwise you would have to specify the exact order of the bits travelling down the wire. That would be a total waste of time! In this case we are going to build our new meteorological protocol on top of SOAP. We could also specify a binding based on the HTTP protocol that is used by Web browsers. However, each port may support only one binding. For the service to support both transport protocols, we would have to define separate ports, with names like temperature_soap, and temperature_http. Both ports would support the same operation; only the transport protocol would differ. The WSDL spec describes how to use WSDL with SOAP and HTTP. Third parties could define how to use WSDL with (for example) the popular mail protocol SMTP. Any existing transport protocol could be used, but somebody, somewhere would have to write a document explaining how WSDL and the protocol fit together. The binding does more than just choose the transport protocol. It also specifies some details about how to use the transport protocol for each operation. These details depend upon which transport protocol you have chosen. For instance if you choose SOAP, you get to choose options that are available in the SOAP specification and generally tweak the layout of the SOAP messages that are sent across the network. 23.1.4 Getting abstract: port type Each binding is associated not only with a transport protocol but also with a port type, which is a set of operations provided by the service. All the operations of a service are grouped into one or more port types. In our example, we've created three port types with one operation each, temperature, humidity and pressure. This is the layer at which we start to lift off from the very concrete into the land of the abstract. The bindings and ports were concrete in that they defined how the information would be laid out in terms of SOAP messages (or HTTP messages) and where on the Internet the messages would physically go. Port types are abstract. They do not say what exactly should go on the wire nor where that information should go. Rather they define in the abstract what sort of things can be said. That means, for example, that an industry group could define a single port type for handling temperatures and then specify a variety of bindings for it. Doing so would allow some Web services to handle temperatures using SOAP and some to use HTTP (the protocol for the existing Web and REST Web services). Service providers could compete based on which concrete bindings they provide for the same abstract port types. 23.1.5 Defining behavior: operation Each port type has a name and a set of operations. Any Web service that claims to support the port type must have concrete bindings for each of the operations. Just as a DTD or schema requires many XML documents to have the same element structure, all ports of the same type must support the same operations. Operations are defined in terms of input, output, and faults. Imagine a real-world service for delivering pizza. To place an order, you must give the pizzeria a list of toppings, an address and a credit card number. In WSDL terms these are the input to the process. Hopefully you will eventually get a pizza. This is called the output. If something goes wrong, you can expect a phone call along the lines of "we could not find your house" or "we could not process your credit card." These error messages are called faults. 23.1.6 The information unit: message In our meteorological example, the output certainly is not a pizza and a fault is not a phone call. Web services deal in information represented as XML. The unit of information sent back and forth between programs is an XML document called a message. Operations define their input, output and faults in terms of messages. The operation query_temperature would have as its input a geographical location. Users are probably interested in the temperature where they live! We would therefore define a message type for asking about the temperature at a particular point on the globe. It might also allow the user to specify whether the result should be in Celsius or Fahrenheit. The output would be another XML message, containing the temperature represented as an integer. We might send fault messages for requesting an unsupported location (e.g. Antarctica) and for requesting an unsupported temperature unit (e.g. Kelvin). Let us say we called our output message type temperature_report. The interesting thing about this element type is that it could be useful in a totally different operation, wherein a remote weather station reports the temperature to our server. For that operation, it would be an input message rather than an output. In other words, the remote station would contact us and send a temperature_report message as input. Later, an end-user could request the neighborhood temperature and we would send another temperature_report message, this time as output. 23.1.7 Composing messages: part and type Each message has one or more components, called parts. Every part is an element, either one whose content is a datatype defined in the XML Schema specification, or one that conforms to a defined complex element type. For instance the input to our query_temperature operation would need a latitude and longitude. Each of these could be a part with data content conforming to the XML Schema integer datatype. Alternatively, we could define a single complex position element type with subelements or attributes for the latitude and longitude. We would then refer to that one element type in our message part definition. It is possible to define new element types by embedding their definitions right in the Web service description, or else by referring to external schema definitions. You can define types that are very simple, such as credit card number, or very complex, such as purchase order. Creating definitions in WSDL is easiest with the XML Schema definition language (XSDL), but other schema languages can be used as well. 23.1.8 Summary of WSDL Here is a summary of the WSDL hierarchy shown in Figure 23-1, working from the top down. Now the details we encouraged you to skip the first time should be meaningful. service A Web service performs operations.[1] These are grouped into one or more sets, called "port types". Each port type is accessed from one or more ports. [1] If you think of a Web service as an object, the operations are its methods. ports A port establishes a binding between a port type and a Web address for accessing the port type's operations. There could be several ports of the same type, each bound to a different transport protocol. The addresses of a service's ports could point to the same or different machines. bindings Bindings are the links between the physical implementation of a Web service and the abstract interface. Each binding specifies how a particular transport protocol is used for the operations of a given port type. port types The operations provided by a Web service are grouped into one or more port types. Port types define the abstract interface to a Web service. operations An operation could consume a particular input and/or produce a particular output. If errors occur, it could also produce faults. Inputs, outputs, and faults are types of messages. messages Messages are XML documents. They are made up of parts. parts A part is an element of a specific type. types Part types can be complex element types (with subelements and/or attributes) or simple datatypes. They are typically defined in XSDL. The layers obviously go from most complex ("a complete Web service") to simplest ("a single element"). They also go from concrete implementation ("send these bits, to this URL, on this machine, using this transport") to abstract interface ("the types of things we are talking about are temperatures and air pressures"). Most importantly, the layers go from most specific to most reusable. Compare the definition "Sal's Pizza on the corner of Main Street and First Avenue" with the generic term "pizzeria". The first is very specific because it includes a concrete location. Web services also have one or more concrete locations because they are provided by the ports. It is the lower layers that are reusable and might be defined by an industry consortium rather than a specific company. There is not necessarily anything company-specific about bindings, operations, messages or element types. In many circumstances it would make sense to share these and have multiple competing implementations. But it would never make sense to share ports themselves. It is no more possible to "compete" by sharing a port than it would be to open two pizzerias at the same address! | 
