RESTful web services: trying to achieve HATEOAS with custom XML

Question

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</resulturi>

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.

Ambassadress

> I know that this 'breaks' the H part of HATEAOS. Does it? I was unaware that HATEOAS puts constraints on the kind of content-types you can use. – Enzyme

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.

Brynnbrynna

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"
}

Overstuffed

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</result>

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.

Thyrotoxicosis

The first two examples required out-of-band information for the client...and so they are not RESTful. – Southport

This is how the anchor tag works in HTML -- A HREF. The media specific processing rules allow for relative urls. – Thyrotoxicosis

Answer 4

I would suggest that rather than hand code these hyperlinks, use a tool which creates those hyperlink for you. Interaction oriented programming is a good method to create these interactions (hyperlinks). Please follow this link this technology worked for us http://www.masterkube.com/hateoas_technology.html

Oriflamme

While this link may answer the question, it is better to include the essential parts of the answer here and provide the link for reference. Link-only answers can become invalid if the linked page changes. – Fiore

Answer 5

At a very minimum (even if you do nothing else), you should put your URL in an XLink attribute instead of the element content:

<resulturi xlink:href="http://resultserver/results/1234.xml"/>

XML processors are able to parse and follow these as URIs natively. As a general rule, text which is not translatable or could never have sub-elements should be in an attribute to enforce such restrictions.

But beyond this, do what others have suggested and define your media type so that the meaning can be understood by clients.

Buntline