The Basics of Web Services

As with any programming language, architecture, or standard, you must become familiar with a lot of terminology before you can start implementing anything. So I'll start by introducing some of the basic terminology and technologies you need to understand before coding your own web service clients and servers. Don't worry: I'm not going to go back to ground zero and explain XML. Nor am I going to give you a blow-by-blow description of what's in a WSDL document.

Probably the most important thing to cover is the idea of web service signatures. Web service signatures are really just data types that the service either expects or returns. Web services are not language-specific: you can use your programming language of choice to implement a client or a server. A client written in C# or Java must be able to communicate with a client written in Ruby, and vice versa. One consequence of this is that, to be compatible with strongly typed languages like Java, web services must also be strongly typed. For the most part, the object types you are likely to come across in web services are things you would expect: integers, strings, booleans, floats, and datetime types. However, web services often deal with more complex types as well, such as arrays and structures. From a Ruby point of view, dealing with all these different data types is really quite simple. All the standard data types basically map to their Ruby counterparts, arrays map to Ruby Arrays, and structures map to Ruby Hash types. You'll see these standard types in action through the examples.

Another important piece of understanding the web service puzzle is the WSDL file. WSDL stands for Web Service Description Language; a WSDL file is an XML document that defines the interface to a SOAP service. WSDL files provide details about the methods that the service exposes, the methods' arguments and return values, and the encodings used for data traveling between the client and the server. Everything you would ever need to know about a SOAP service can be described in a WSDL file; WSDL files serve both as a form of documentation for SOAP services and as a key to automating many of the steps of building SOAP clients. Thus it's possible to read a WSDL file and find out everything you need to know about the API it describes. WSDL is documented at w3.org and in many site about web services. Reading a WSDL file isn't fun, but, fortunately, it's hardly necessary these days (though still a good skill to have). The primary use of WSDL is to automate the client code so that you don't have to explicitly write code to handle different data encodings, different mappings between object types, and so on. (I'll talk a little bit more about using a WSDL file to automate some of your client code in the Google example.)

Where does this complex, magical WSDL file come from? In the bad old days, it had to be written by hand. But most modern web service platforms automatically generate WSDL files and make them available for clients to download. Rails is no exception. (The SOAP server example in this document includes a WSDL file that is automatically generated.) Given that the WSDL file is automatically generated and automatically consumed, you should never need to touch it.

Finally, I need to say a little about web service architectures. SOAP grew out of XML-RPC, so SOAP services and XML-RPC services are fundamentally similar. Both try to mimic "normal" programming operations: function calls (for XMLRPC) and remote method invocations (SOAP).

REST services represent a significantly different (and arguably much simpler) paradigm. REST stands for Representational State Transfer; the most authoritative description of this architecture is in Roy Fielding's dissertation, located at ics.uci.edu/~fielding/pubs/dissertation/top.htm. The basic idea behind REST is that you don't need to make web services "look like" regular method calls or function calls. The basic HTTP operationsGET, PUT, POST, and DELETEcorrespond nicely to the four basic SQL operations: SELECT, UPDATE, INSERT, and DELETE. Therefore, it's possible to build complex applications by doing nothing more than using HTTP requests to move XML documents around.

With REST services, there is a lot of debate between purists (who have a fairly strict interpretation of what each operation should be used for) and others, who've basically said, "Let's build applications by pushing XML around; who cares whether it corresponds to a nice architectural model?" The debate between the people representing these extremes can become heated; most REST sites in the real world fall somewhere in the middle. Since my goal isn't to teach you everything there is to know about web services, I sidestep most of this debate and simply show you the easiest way I know to make each type of server and client work with Rails. I leave it up to you to decide where and when to adhere to various web service practices.

We've covered enough of the "getting started" material, so let's dive into the fun stuff and look at the basics of each type of client and the steps you need to get them working with your Rails application.