karniv0re's Journal: Hating HATEOAS and a New Whiteboard

I'm designing a REST API kind of from scratch. Actually, I'm taking an existing API in production, and putting kind of a "Version 2.0" on it, leaving the original in place, but making the v2.0, well, better.

So I've decided to read up on REST and instead of just attacking it like I have every other RESTful project I've done, actually approach it with an architectural mindset with some theory to back up the practice. So I read about the Richardson Maturity Model, about how most of my services up to this point have been Level 1 services, which is fine, since I was the only consumer of them. But now that I'm going to be exposing this to the world (at least a subset of the world), I want it to be done right. At least, as "right" as I can get it given all the conflicting information on REST.

The biggest problem so far is, I'm building this with Content-Type=application/xml, not Content-Type=application/json. Why? Because I don't think our consumers are going to be big JSON users. To that end, I don't think they're going to be big HATEOAS consumers either. However, I want to do it this way anyway, so no one can say we weren't forward thinking. So back to the XML problem - there are like, ZERO examples of an XML Hypermedia API. Everything is in JSON. Even the RFC for HAL is for JSON. Why not include XML in that? The two go hand in hand. It's just a different dialect for the same data.

After exploring two frameworks for HATEOAS (spring-hateoas and Jayway Forest), I found that there's nothing that will support XML. So I'm rolling my own. I guess it's pretty simple, we're just representing links, right? But it's a little bit trickier because link displaying is dynamic. So I need a way of conditionally displaying links. I'm leaning toward annotations. I got this idea from Jayway Forest. That seems pretty basic.

And it's looking like the closest thing to a standard is HAL+XML, which isn't even an RFC yet, but a guy on Google Groups who just modified the RFC for HAL+JSON and posted it to Github. Man, this is looking ugly. So, in light of this, I'm thinking there really is no standard, and I'm just a well off writing my own as trying to follow someone else. So that's what I'm doing.

Previously we were returning XML that looked like this:

<{specific-type}-response>
    <response-header>
        <status-code />
        <status-message />
    </response-header>
    <{some-specific-entity}>...</{some-specific-entity}>
</{specific-type}-response>

There are a bunch of problems with this. First of all, the root element changes for each Controller. That makes it very hard to write a client.
In fact, calling it any kind of response is incorrect. That is a Java developer habit. We write everything with services, so everything is a request/response. But here, the response is the entire package - HTTP Headers, Status Code, and Payload.

Secondly, why is there a response header in the response body? We get that for free with HTTP! Get rid of that thing and we're already starting to creep into RMM Level 2!

What we're representing in XML is the Entity, or Resource. A Resource is just a representation of an object's state. Like a lightbulb:

<resource rel="self" href="/room/kitchen/lightbulb">
  <link rel="switch" href="/room/kitchen/lightbulb/flip" method="PUT" />
  <link rel="change" href="room/kitchen/lightbulb/change" method="POST" />
  <light-status>ON</light-status>
</resource>

One thing that isn't in the "spec" if you want to call it that is the method there. That at least tells the client what I'm expecting for the verb.

I'm really torn on all of this, as I'm sure many other developers trying to implement this kind of thing are. Nothing is concrete and there's pitfalls everywhere. I know it's been like this for a long time, but it just seems like the more it gets refined, the less anyone seems to know what to do with it.

Oh, and my whiteboard got replaced today with a smaller one. The super annoying thing? I had my whole REST API written up on it for reference. Motherfuckers.

Why offer only xml?

[Rasperin]

(All part of the org.json library, since you are using spring I am assuming you are working in Java but most languages have xml/json parsers)
JSONObject json = new JSONObject(str);
String xml = XML.toString(json)
http://www.json.org/javadoc/or... [json.org]

Or do you not have access to a Java backend and I misunderstand (and it all has to be done in HATEOAS)?

Re: Whiteboard, yeah I freaking hate that. Don't you people understand people do important work on these and they should never be erased or taken without pe

Re:

[karniv0re]

I'm in the transportation world, and most of our partners and customers are still on EDI. So, while my code can easily be modified to support JSON (indeed, our internal products only use JSON), XML seems to be the choice of the industry. I'm going to wait for the use case to flip the switches for JSON, since I'm mostly focusing on getting this out the door. Though admittedly, this is a weak excuse not to implement it out the gate because I don't want to deal with it at the moment. Anyway, I think I have it

Re:

[Rasperin]

Cool, I'm looking forward to what your solution was! Finding easy ways to transform an object into xml has been difficult for a great long time. There's solutions like JAXB but I really do not like generated classes. I'm also curious if you went with a framework solution or a java general solution.

Re:

[karniv0re]

I am using JAXB, actually, and I don't hate it, but I don't love it (for hatred of Java/XML see JiBX). I was hoping to have a base class that would have a root node called "resource" that would contain a self link and a list of links. But for some reason you have to put the root element in each inheriting class, so I have all these inheriting classes with stupid @XmlRootElement(name="resource") at the top... I dunno, it looks like it'll work, just not as elegantly as I had hoped. My biggest problem was unde

Re:

[karniv0re]

As an anecdote to why I'm using XML, on the conference call today with our partner, I was explaining the API to their lead developer, and he actually asked, "What's REST? Is that like, a framework or something?" hooooboy.

Re:

[Rasperin]

I'm not sure if you read through the solution I proposed though, the idea above is that you would generate both json and xml (actually specifically it would be json->xml and it would look like this):

public static String createXmlObjectFromPojo(MyPojo myPojoIAmTransforming){
JSONObject jsonObj = new JSONObject(myPojoIAmTransforming);
String xml = XML.toString(jsonObj);
return xml;
}

In a handy little static util (5 lines of code), but then you could take it further and offer BOTH JSON or XML (esp if