WS-* – the Void

I’ve been researching Web Services and Web API when I came across this cunningly-named protocol: REST*.

I’ll try to put together the key points and pointers that I collected in my journey and try to give an introduction to the whole affair.

What Services?

Web Services is the fancy name behind the simple idea of making documented requests to load/store some data from/onto a web server. The idea is simple because you could (and some did) do much of the same things if you were smart and determined enough., way before the name was invented. Consider getting some HTML page and parsing data from it. Same would be true if one knew the parameters of search queries, generate the POST or GET commands on HTTP and processed the returned HTML files. Through hackery, one could do quite a bit. But any change in the web site in question, and your code would break; you’d have to re-hack it.

The main advantage of web services I’ve already mentioned; they are documented. This is not a trivial fact. The details of the resources (or services, to use the new terminology) are well defined and documented (no need to guess the POST details or URI structure and naming) and not only that, but the results are in well-formatted and documented form (typically in XML, but YAML is making headway). So the whole thing can now safely be called API (Application Programmer Interface). In addition, more of the internal functionality are usually exposed, where before one would be limited to whatever public services were available.

At some point some web sites thought it would be a good thing for their business growth to give more power to the users and 3rd party vendors. They documented their service interface. More accurately, they added a 3rd party API to their internal system (typically as an afterthought). Many followed suit. Now it’s usually designed into new web sites and web applications.

Not surprisingly there are many ways to go about designing, implementing and accessing web services. The roughest approach is some form of RPC, while mature form would be something like SOAP. REST, on the other hand, is somewhere in between. Apparently there was a huge debate about it (I’m not sure it’s settled).

According to Wikipedia:

REST strictly refers to a collection of network architecture principles which outline how resources are defined and addressed. The term is often used in a looser sense to describe any simple interface which transmits domain-specific data over HTTP without an additional messaging layer such as SOAP or session tracking via HTTP cookies. These two meanings can conflict as well as overlap.

So what is REST anyway?

REST (Representational State Transfer) is an architecture of structuring, organizing and managing (at runtime) a set of resources and services. REST overloads the existing resource identifiers to create, read, modify and pass state information from one to another.

REST Principles

Here are the main REST principles in a nutshell:

URI’s are the API; create the missing, view/edit the existing, delete is terminal editing.
The server is stateless; state transitions are in the URI’s.
XML is not necessarily the format for input and output; use whatever is handy.
HTTP is typically used for the communication layer; while canonical, HTTP is replaceable.

Conclusion

After reading many debates and comparisons between the REST approach, RPC and SOAP (and other WS-* protocols) I think I’m of the opinion that REST is the way to go. It has so many advantages that appeal to me that it’s hard to see why not use it. WS-* seem to have its use cases too, but it’s a rather limited one.

REST is very simple and is a natural fit for the web. If you have even the most static web site, it’s a rather retarded form of REST. However, to have the simplest working WS-* protocol, you’d have to invest an untold amount of time and energy. In addition, REST is the simplest thing that works, which translates into flexibility points. The more rigor and formality you put into a system, more robust it might seem, but also much harder to adapt and change. REST drives its rigor from the high-level principles that, when followed, give high predictability to the system.

It’s like your classic monolithic concrete building; once you poor the concrete in the casts, you can’t change without blowing it up and starting over. On the other hand, a more modular and componentised approach will give you the flexibility of changing the shape and form of your structure over time. As things mature and experimentation fades into a working system, one would undoubtedly need to make non-trivial changes. Any of the gorilla-sized WS-* architectures would be a liability at that point, when REST is ready for change.

* Generally speaking REST is how the web works. It’s not a novelty, just a fancy name given to the architecture.