//log//

Eventually a rather short thought relating to my attempt trying to, well, build a better mouse trap. Maybe in course of exploring things and slowly growing a technical environment into something new, there’s always the chance of discovering a show-stopper to immediately prove a given approach limited or even wrong altogether, but at the moment, I am pretty much entertained by following HATEOAS and HTTP ‘ideas’ for building an (external, internal, whatever) system interface all anew. Why?

Well, I could go on for quite a while outlining the many smart things in this approach that have been discussed and pinned down at length elsewhere, and that have come to be looked at as considerable and worth thinking about for a good reason in my opinion. And yet, there is one thing that might go a little unnoticed in this whole mess: “Accessibility” for developers, lacking a better word for that. What was the last time you tried exploring and working with functionality spread out all across a bunch of different @EJBs in a larger Java EE application? You’ll be capable of doing so, no doubt, but initially, you will have to cope with quite an infrastructural hurdle of dealing with things. You will have to figure out which beans provide which functionality, you will have to figure out which EJB interface does adhere to which semantics, you will have to figure out how to, at best, “get” basic remote data objects to work with, and, eventually worst of all, you will have to make it across a technical hurdle of connecting all your mess to the remote application server, having at hand all the right client libraries required both for generally building Java EE / EJB applications and, more specifically, for building and running EJB client applications with your very special container of choice – whereas resolving @EJBs is next to trivial in up-to-date Java EE 6 containers using resource injection or portable JNDI names, dealing with remote clients again (still?) ends up to be rather container specific. Sure, this complexity is not (just) around for the sake of it but, overally, because the kind of applications Java EE are thought to be distributed, complex and yet robust.

And yet, in this situation eventually your new developer does spend a substantial amount of time dealing with infrastructure before getting anywhere. And this is, overally, where the REST/HATEOAS approach starts being interesting. All this given, your world’s pretty straightforward – all you need is a browser, maybe something like cUrl or http-console and a fundamental understanding of how HTTP works. And you need some sort of entry point, an “initial resource” to work with. And then – you’re almost ready to go:

• Starting with your “initial” resource (which, in our case, happens to be a representation of a “project”), you are able to literally “browse” a web of data and, this way, explore how things are linked together. You’ll see the project referring to a collection of documents, to a set of users, you’ll see each user referring to a couple of orders and “submitted” documents, you’ll see each document referring to a bunch of different versions and in each version to possibly a bunch of different data files.
• Starting out browsing, most of what you will eventually do is using HTTP-GET for retrieving and viewing resources either manually or writing small scripts to explore things for you, not unlike “fetch object, extract any hyperlinks, fetch more objects”, ad infinitum. This way, you will either manually or programmatically start dealing with the structure of the resources you recieved, with the information they hold and the relationships between each of these resources, its direction and cardinality.
• Maybe, by then, you will start playing with HTTP Accept and Content-Type headers, learning that different kind of server-sided data is represented in different ways. You’ll see a resource representing some sort of image in a database returning complex metadata while being requested in an application/json representation while returning the actual image file when asked to send image/jpeg. You might even see a roughly drafted HTML form allowing for interacting (showing, navigating, posting/modifying) data entries via their representation accessing the resources using a browser while, at the same time, you get clean XML or JSON using a “programmatic” client.
• Ultimately, becoming a bit more courageous, by then you might try other HTTP verbs (POST, PUT, DELETE) and see that, eventually, that these do have an effect on the data you are dealing with. Or maybe they end up with messages you are familiar with – HTTP 401 Unauthorized, HTTP 403 Forbidden, HTTP 409 Conflict, HTTP 201 Created. You know the web, so you know their implications. And, along with this, you might want to play with ETags and caching, figuring out you don’t really have to deal with that large business object again at the moment because it hasn’t change since you last checked.

Yes. If you’re used to Java EE, EJBs and Java in general, there’s quite a bunch of things that might scare you off here. If you’re using readable JSON, chances are it’s anything but typesafe. Maybe you might want to object against using a data representation which is by no means validable, or you might be scared off by seeing that, in the end, it’s all about communicating via HTTP whereas your EJB client could make use of EJB-Remoting or CORBA for these purposes without all the fallacies and drawbacks of (de)serializing from/to text. You might argue that manually reading references and representations is a pretty painful way of reliably understanding of how things are really put together. And maybe you’re even right. But, in the end, given a well-crafted REST interface, there’s two things you have at hand here: An awfully accessible and fast way of exploring your business domain model in a way which is some balance between “formal” and “non-formal”, and a learning effect that, this way, application design in itself could happen completely different (just thinking again of the idea of HTML resource representations for GET/POST/PUT/.. instead of web based “user interface layers” in a “traditional” MVC approach).

And, after all, no one says you only need to go with REST/JSON/…: Using the JAX-RS API for RESTful web services which is part of recent Java EE specs, no one keeps you from building robust, scalable, secure Java EE web applications and exposing parts of your functionality in a RESTful way – with all the benefits (and hazards) this approach has. And this ain’t all too bad, is it? Yet I am curious to see how a “real-world” project based upon a RESTful API will work out a couple of years from now while undergoing its first serious rework. Will it, by then, still be “nice”? Or will it, by then, have gone all the same way SOAP went, back from these days before WS-*, back from these days when it still was considered a Simple Object Access Protocol and a “lightweight competitor to CORBA”? We’ll probably see.

Filed under: