karniv0re's Journal: Less Hate for HATEOAS

I'm starting to finally warm up to this whole Hypermedia thing. It's really not so terribly difficult to understand.

I actually figured it out on my way to the Slayer / King Diamond show. It was a bit of a walk for me, so I use that time to think through my projects without being at my desk. Helps get me outside the problem and see the forest for the trees.

It finally occurred to me that we're using controllers to provide methods. Those methods either return a resource (a mapping of an entity), or perform some kind of action on a resource. The action performed is declared by the client in the HTTP Method. GET returns a resource. POST and PUT do some kind of modification to a resource (the difference being POST is not idempotent, a word that I have just this week learned).

So on my walk, I realized that everything in a GET is just a resource. Why not just name them all "resource"? The client should be able to figure out what kind of resource it is based on the URL. I think the key to reaching REST glory is understanding that HTTP IS THE FRAMEWORK. Every REST service I've written up to this point has been like, "/service/something/do" or "/stuff/morestuff/get". Why?! There should be no verb in the URI. That comes for free with HTTP Methods! And all these verbose responses with error codes in XML and shit? C'mon, that is given to us in HTTP Response Codes! And I think once that realization hit me, everything came together (in my brain, still lots of coding to do).

As a previous comment asked how I am serializing XML, well, it's with JAXB. Seems to go hand in hand with Jersey, so I'm not going to rock the boat. I actually briefly tried Spring HATEOAS, and it didn't play well with Jersey. Couldn't find the servlet context, probably because Jersey had it. I dunno, didn't dig too deep on that. It's such a simple concept here, presenting links to allow for a responsive API and client, it wasn't hard to roll my own.

So all I did was create a HypermediaLink object that just holds basic string stuff like rel, and href. Then I created a BaseResource that holds at least a selfRel and a list of links. My resources extend this, but here's the dick kicker - the @XmlRootElement(name="resource") has to go in the inheriting class. No way around that with JAXB, unfortunately. So that's not super clean, but at this point, we're splitting hairs.

So armed with that plan, I drew up my API state diagram. It's still a work in progress, but all the sudden it feels SO CLEAR what needs to be done. So now I just need to do it. Hard part is over though. I'm actually very happy with my work, thusfar. Looking forward to banging this out and chalking up another huge win.