WEB Advent 2008 / Which Web Service?

We have seen a dramatic rise of the SOA (Service-Oriented Architecture) in our shiny new Web 2.0 world. Every site has an API of some kind and no self-respecting software project can be seen to be developing without one. But is there more to it than buzz-words and hype? And how can you find which kind of service will work well in a given scenario as well as being reasonably easy to implement?

I think that services are actually very cool and useful—once you get past the people-full-of-hot-air problem (yes, just like iPhone owners; it’s cool, but not that cool). Implementing a service with useful functionality in a sensible way is quite a challenge, so here’s a quick overview of the different types of service to help illuminate the issue.

SOAP

Happily, SOAP has grown up and come to terms with the fact that it isn’t simple at all, so “SOAP” is just a word now, and not an acronym. SOAP has been around for a while and is used widely in quite a few different technology spheres. In PHP 5, working with SOAP is astonishingly simple, so SOAP can seem like a simple choice.

Look out for the pitfalls, however. Firstly the WSDL (Web Services Description Language), which defines the service. WSDLs are there to very specifically state what functions are available and what data types are expected and returned. This is pretty tricky in PHP because we work with weakly, dynamically-typed variables, so the rigid nature of WSDL doesn’t fit too well. Actually getting a working WSDL is a big challenge, mostly for this reason. There are a few tools around to generate WSDLs, but be aware that this is a bit of a minefield. It can also be quite tricky to get a PHP SOAP server to talk to a SOAP client written in another language, so do proceed with caution if you go down this route. It can sometimes be more helpful to use SOAP in non-WSDL mode if compatibility issues arise—but this sort of defeats the object of SOAP.

SOAP is usually a simple RPC (Remote Procedure Call) interface, meaning it maps incoming requests onto particular method names, and this can be quite limiting in itself.

Some Notes about RPC

RPC is a way of allowing external things to make calls against methods or functions within your system from outside. This means that you are literally exposing a wrapper to (probably) a library class of methods. Which is great if that’s the kind of service you want to provide and this fits within your application requirements. It is worth considering other approaches, however, as this can be quite rigid.

XML-RPC

This is possibly the simplest way of exposing system functionality over a web service. A service of this type typically uses HTTP (HyperText Transport Protocol) to communicate XML (eXtensible Markup Language) requests and responses. XML-RPC was a precursor to SOAP and there is a lot to be said for a very simple service to be supplied along with completely separate supporting documentation! Often, if you are supplying a service to a client, you’d be expected to supply a manual and some working examples anyway.

XML is widely used and understood, and can be interpreted by most languages. This makes it a good, solid choice of data format to use for a web service, which may be consumed by various users and platforms.

JSON-RPC

This is (as you may guess) very similar to XML-RPC, but uses JSON (JavaScript Object Notation) as the data format. Contrary to what you might think from the name, JSON is a format understood by most languages—PHP can read and write JSON very easily, and internally it looks a lot like a serialized object (because it is).

This is another very simple format which is ideal for cross-language applications and works really well when published with good documentation.

RESTful Web Services

A RESTful service is a slight misnomer, since REST (Representation State Transfer) is an idea, a concept, and nothing to do with protocols or data at all! REST is a set of principles that considers everything to be a resource with its own unique global identifier. In fact, it is much more like making a web request to an application and getting a response, and the internal code looks pretty similar too in terms of routing requests and returning them in the correct format.

Operations can be carried out on these various resources by addressing their unique identifier (a URI when we use REST over HTTP), and it’s common to use the HTTP verbs GET, POST, PUT and DELETE to indicate that the resource should be returned, updated, created or deleted accordingly. It’s fairly typical to use XML and HTTP to build RESTful services—but that’s separate from the theory of REST itself; JSON could be used just as appropriately here.

Web Service Selection

In conclusion, it is worth taking a moment to consider the options before you actually start building your shiny new web service. Whether you are wrapping an existing library, creating an interface between two applications, or already have requirements in place for your project, I hope this has helped provide some perspective on what is out there and the various types of service to choose from.

Other posts