Skip to main content

How RESTful is your RESTful application?

Posted by mkarg on February 20, 2010 at 8:46 AM PST

What it means to speak German fluently and to be able of C++

Several years ago one of our key coders moved from the south of Germany (where our HQ is located at the Black Forest) to the cold and rainy north, so we had to to find a suitable substitute. After screening lots of applications, we picked few to invite for an interview. It declared the candidate's ability to speak German and C++. So she was the first one getting invited into our office rooms to fight her thesis of what she declaratively would be able of.

You must lie, sometimes.

We had been somewhat shocked that the person was actually speaking Russian fluently but her German was rather, well, a mess. It was just hard to in fact at least interview her about core details like where she was coming from and what she graduated in, without falling back to English or drawing sketches. Her German was actually so bad that she had problems to understand many of our simple questions, and we had problems to understand her answers. Asked for the reason why she declared to be able to speak German, she told us that she understood that without this declaration it was obviously impossible to get invited for the interview (which was true in fact and was very frankly), and that the fact that we understood this justification would be an actual proof that she is able to speak German - at least somehwat. As we couldn't abstain to agree in both, we hired her and she is working for us as a programmer for several years now. It seems, one must lie (at least in details) sometimes.

Good enough for daily use.

Years later I passed her desk by incidence and looked on her screen. I noticed that her C++ code actually looked very much like well-structured C but less like plusplus. So at a cup of coffee I started a discussion upon several aspects of the difference between C and C++ to find out about the reason, as I always thought that she is much better in C++ than I am, as I turned to Java more than a decade ago leaving C++ behind. It turned out that we never noticed that she in fact knew only some of them and applied just those few regularly, but others had been not known at all or had not not getting ever used, since they where misunderstood by her (like "seldomly" used things like exception handling or reference types as she titled it). From an OOP point of view, her code was just a complete mess and showed clearly that she did not understand the key idea of OOP actually and what she did was C-with-classes but not C++. So I asked her why she never told us that she knows C++ only a bit so we could have sent her to a C++ training? She said that she actually didn't know that she only knew half of C++ and that it is not OOP what she is doing every day. When asking her whether she didn't notice that her code looks completely different than mine, she answered that she did notice that mine is much better to read and much more stable, and applies much more patterns and so on, but she just had not the idea to copy my style as she thought what she did would be "good enough to get the everyday tasks done". I didn't know what to answer, actually. It seems, one must not really understand something completely, to get the daily work done more or less successfully.

What I learned from this anecdote is that in the real world sometimes you must lie about what you are or can do, and that it is not an actual problem that you declare things that you cannot fulfill. You possibly won't reach your target without lying. And it often is not necessary to actually be able to do the declared things to reach the target. So false declarations are more common than one might think or confess, and we all are used to it and live with it without a real problem.

A Pack of RESTful Lies

These days lots of applications claim to be RESTful. RESTfulness is the overall buzzword for virtually each new service. If you write something that can be connected to another computer, call it RESTful. This is at least what happens "out there" every day. Sometimes without a better knowledge that it is untrue (thanks to marketing teams applying the abovementioned idea of "Somewhat German is German!".). But more often with a better knowledge that it is at least not completely true (thanks to engineering teams applying the abovementioned idea of "Good enough for everyday use."). What a pack of RESTful lies!

Certainly, marketing is a hard job, and telling "not the whole truth" is part of it. Whether this implies that it is useful to put exactly the "REST" badge on your package while in fact you do nothing else but simple GET and PUT, is doubtful. Your customers will learn some day, and maybe they might opt to cancel the contract (and justifiably so!) in case they relied on real RESTfulness, since they actually need it? What then have you gained but solely costs? At least my company so far abstained from using the word "REST" in marketing overhastitly, due to this possible risk induced by the technical fact of missing HATEOAS.

Also, yes, it is certainly very pragmatic to only implement those parts of an idea that you need right now. But possibly tomorrow you will notice that your system would be much easier to finish if it would be completely RESTful right from the start (possibly since a new use case has to be implemented)? I often saw people collapse on scarce time trying to add the missing bricks to a nearly finished application after they notice that now "unforseeably" came up the need to have the rest of REST, too. Damned, if one would ever have told them before! Well... didn't Fielding do exactly that back in the year 2000? Yes, he did. You just won't hear.

So while it might look good from a first glimpse to use the word "RESTful" even if it is no completely, doing so will imply problems. Whether those are severe or not, is up to your personal decision. For me, I would never call a system "RESTful" if it actually is only in part.

The Lesser RESTful Application

At this point I'd like to point out that there was an interesting discussion on the rest-discuss mailing list on Yahoo this week about how to title such applications then with another buzzword instead of "RESTful", more or less for the sole sake of marketing, as nobody actually would know the actual technical content of such a "less-RESTful" application. I doubt that neither people will agree upon another buzzword as-smart-as "RESTful" nor on at least not to write "RESTful" on their application anymore, as it is just too tempting for marketing guys to stick a well-known badge on the package instead of a less-well-known-but-technically-correct one. Let's see what they come up with finally.

Resist the Beginnings!

Also there was another discussion on users@jersey.dev.java.net this week, kicked off by myself, about the fact that a proposed Hypermedia API extension to JAX-RS (Java API for RESTful WebServices) possibly allows people to write less-RESTful applications or (in theory) non-RESTful ones. As it is the Java API for REST (and not just some API for REST written in Java), I opted not to adopt such an extension, as people would write RPC-style applications and justify the REST badge on it by the fact that it was written with JAX-RS which "by definition" result in RESTfulness. The discussion moved on to the more general question, whether the Java API for RESTful WebServices shall enforce RESTful style, and I was more or less horrified by the "official declaration" of the spec leads' goals: Their target is "just" to support RESTful style if wanted by the user of the library, but they won't enforce it. Moreover they like to move the responsibility and such the decision whether or not an application built on this framework is RESTful to the developer using their library and like the idea to actively support non-RESTful approaches. Wow. So in the end JAX-RS develops to become "Servlets API on steroids", far beyond the core definition of REST. So what comes next, an OpenGL API that allows to not do graphics at all? If I would have that freedom in interpretation of a project's goal at my employer, I would be really, really glad. In fact, he would stop the project since I missed the target.

Since I am not the project lead of JAX-RS but just some small comitter, and since there are more people that love to use buzzwords and pragmatic solutions much more than real RESTfulness, we have to accept this "open interpretation" of the specification title. Whether this is sensible, will gain a real benefit or possibly has an actual negative side effect as supposed by me, will be shown by the future. Currently it seems I am the only one having a problem with putting the REST badge on such an API, but let's see what happens. Maybe my worries are all wrong and all programmers and especially the RESTful beginners will all completely and correctly understand that they have to resist the beginnings on their own and the API will provide no guidance in the RESTful direction. If not, we'll possibly soon find another JSR on the hive of APIs that started with a good idea but just went in the wrong direction.


Note: An overview of all publications, including blogs and printed magazine articles, can be found on my web site Head Crashing Informatics.