RESTful web services: trying to achieve HATEOAS with custom XML

Question

Hi there,

I am working on an enterprise system that will utilise a RESTful web service between mobile clients and a central server. As RESTful as possible, let's say.

My question relates to HATEOAS (hypermedia as the engine of application state), and the use of custom xml in HTTP response bodies.

This system will never ever be used by public clients, but I like the HATEOAS idea of being able to modify the server-side resource allocation pattern later without having to reconfigure each of the clients independently. If we decide that due to scaling issues we need to spread the server function over multiple physical boxes, no problem, this will be reflected in the URIs that are generated when a client (or the server under instruction from a client) creates a new resource.

Our business domain is highly specific and unusual. As such, I would like to use custom XML for HTTP response entity bodies throughout the web service, and the client will parse resource URIs out of the xml in order to stay informed of resource locations that it can use when modifying its own application state. I know that this 'breaks' the H part of HATEAOS.

e.g. when a client POSTs a transaction to the server for processing, the server might include the following xml fragment in the 201 HTTP response body (as part of a larger xml document). The server would also inform the client of the URI for the newly created transaction resource itself, but this would probably only be included in the Location HTTP header.

<resulturi>http://resultserver/results/1234.xml&lt;/resulturi&gt;

Is this so bad? There is very little chance that the clients using this service will ever be browser based. What are the other advantages of hypermedia over delivering the uris as plain text within xml?

I guess I could go to XHTML, but the parser on our mobile platform is much more efficient with POX.

Answer 1

What you are doing by returning an url in resulturi is effectively hypermedia already. The only problem is that you need a media-type that tells the client how the response is formatted so that it can parse the urls out in a predictable and documented way.

Option 1: Create your own media type like vnd.yourcompany.Resource+xml. By doing this you are stating that the media type can be parsed by an xml parser, but it follows some special rules that are defined by your company. At this point you can use whatever standard you want for defining hypermedia links (see this question). One nice advantage of this is that if in 6 months you decide you need to make a breaking change to the format of your XML you can create a vnd.yourcompany.ResourceV2+xml and as long as you were smart enough to use the accept-header on your old clients, you can smoothly introduce the new format side by side with the old one by making new client applications accept the new format.

Option 2: I'm only half serious about this option, but I have considered pushing for a new mediatype called application/hyperxml+xml. The document would follow the same rules as application/xml but would also make use of XLink for hypermedia. This would allow people who are using javascript to parse the XML document to also take advantage of hypermedia in a standardized way.

Option 3: Use XHtml. I don't understand why your parser has problems with Xhtml, but I'll take your word for it.

Answer 2

There are two important pieces of information your RESTful server will need to process requests, regardless of the underlying markup language: a media type and a URI. Assuming a media type for a given URI would introduce client-server coupling. It would, for example, prevent the same URI from ever serving two different kinds of media type.

XML isn't the only option when designing hypermedia formats. Check out the Sun Cloud API, which defines a hypertext-driven REST API based on JSON (although it appears to not use media type with its hyperlinks). It's not difficult to go from this approach to one that combines media types with hyperlinks.

For example, you could define a JSON data structure called Link that looks like this;

{
  "name":"human-readable label for link",
  "uri":"http://example.com/resources/123",
  "media_type":"application/vnd.com.example.Resource+json"
}

Answer 3

Hypermedia does not require HTML or even fully qualified URIs for that matter. If your media type defines a rule for turning some elements of the response into de-referenceable resources then you have hypermedia.

<result>1234</result>

The above example, combined with a media type rule on how to dereference the contents of the result element is hypermedia in the same way that:

<result>/foo/1234</result>

is with a rule to prepend the base http URI. So is the example below where the fact that the http string is dereferencable may be left implicit.

<result>http://myserver.com/foo/1234&lt;/result&gt;

However, while they are all hypermedia and meet that constraint, I would argue against creating your own new hypermedia production rules and tags if at all possible and just re-use existing ones. The first example makes it less obvious to the user that this element represents a hyperlinked resource than the last example.