Web Services Primer

The Wikipedia entry for web service (https://en.wikipedia.org/wiki/Web_service) is a good place to start learning about web services and the family of standards and technologies that make them happen. In a nutshell, a web service is a program made available by its author to other programs on a computer network. Web services usually do useful things–today there are web services that provide real-time stock quotes, translate text to braille, perform complex statistical analyses, and all sorts of other things. For a big list of some available webservices, see
https://www.xmethods.net.

Interfax provides a webservice that programmers can use to add faxing capabilities to their applications. You will see in this tutorial that using the Interfax web service in your Java programs is fairly straightforward and much more practical than attempting to write your own faxing software.

The goal of web services is to enable one computer program to communicate with and benefit from using another computer program. This is the essence of distributed computing and is not a new idea. With the recent incredible growth of the Internet, and the World Wide Web specifically, progammers suddenly find themselves on the same network with thousands of other programmers. This Internet growth has fueled lots of innovation in distributed computing and the newest generation of software applications is built by programmers who understand the power of this computing paradigm.

Motivations for Modern Web Services

Java programmers have had excellent tools for distributed programming for some time. The Remote Method Invocation (RMI) library, released with Java 1.1, made it incredibly easy for Java programs to talk to eachother, essentially allowing one program to call a method on a class running in another program. With the RMI library came Java serialization, an automated framework for sending object instances over a network connection. RMI is one of the greatest Java successes and the most popular way for Java programmers to build distributed programs.

The Internet poses a new and difficult problem because in the real world programmers have dozens of programming languages and operating systems to choose from and making these programs work together is not easy. Java RMI is great for connecting one Java program to another Java program but it’s useless for connecting a Java program to a C++, Python, Perl, or C# program, all of which are very common. Another problem is that the Internet is very security conscious–firewalls block most of the ports two computers could communicate on, including 1099, the default RMI port.

The solution to connecting these varied programs in this restricted Internet environment depends on finding a lowest common denominator, a communication protocol that is as simple as possible and available to all programmers regardless of their operating system or programming language. Also important is to find a protocol that can be used on the Internet without having to worry about firewalls. With these goals in mind, HTTP is an obvious choice as it is extremely simple to use, it’s available on virtually every operating system and every programming language, and it’s the protocol of the World Wide Web itself, which most firewalls do not block.

Simple Object Access Protocol (SOAP)

Having chosen HTTP, it’s important to decide on the types of messages two programs would send back and forth to do meaningful things together. The original designers came up with the Simple Object Access Protocol, or SOAP, to address the structure of these messages. They decided that the messages should be simple to produce and consume and should be human-readable. To accomplish this, they chose an Extensible Markup Language (XML) message format.

Extensible Markup Language (XML) message format.

As a simple illustration, let’s assume you want to access a web service to find the current weather forecast for Chicago. Such a web service exists, and a program wishing to use it would produce an XML message that looks like the following:

<?xml version="1.0" encoding="utf-8"?>

  
    
      Chicago
    
  

The webservice would receive this message, and would produce an XML response for the client that looks something like this:

<?xml version="1.0" encoding="utf-8"?>

  
    
      
        41.8858452
        87.6181259
        0.000401
        17
        CHICAGO
        IL
        
          
            Friday, November 18, 2005
            https://www.nws.noaa.gov/weather/images/fcicons/nsn.jpg
            39
            20
            4
            -7
          
          
            Saturday, November 19, 2005
            https://www.nws.noaa.gov/weather/images/fcicons/bkn.jpg
            43
            33
            6
            1
          
        
      
    
  

There’s really nothing magical going on here. One computer program sends an XML-formatted text message asking for weather information for Chicago to another program using HTTP. That program responds with an XML-formatted text document which includes some weather forecast information for Chicago. This is a very simple conduit between two different programs which don’t need to be written in the same programming language, and don’t need to be running on the same operating system. All SOAP communications happen like this, with the simple passing of XML messages between programs.

Web Service Description Language (WSDL)

While these messages look simple enough, a programmer has to know ahead of time how to format an XML SOAP message before sending it to another program. Also, a programmer would need to know what information to expect in the response document and how it will be formatted. In SOAP, each web service is described by an XML document formatted according to a standard known as Web Service Description Language (WSDL). When a programmer builds a web service, they provide a WSDL document which specifically describes how request and response messages should be formatted and also provides additional information. For example, the types of “faults” or exceptions that the caller ought to expect if the service was unable to fullfill a given request. As an example, here’s an abridged version of the WSDL for the weather web service above. Don’t worry too much about the details now, just notice that it describes what the web service does, how it can be called, and how request and response messages should be formatted. (For the curious, the full WSDL can be found here):