2

Edit: To clarify, this question concerns building GUI applications on HATEOAS APIs, how to design interfaces built on hypermedia "discoverability" (ie. dynamic) principles, and specifically dealing with avoiding purely "modal" GUIs that "link" back to "home" for global functionality that should be "always on" (as represented by the hypermedia entry API point).


In a strict REST API implementation, utilising Hypermedia As The Engine Of Application State (HATEOAS), what patterns (if any) are used to indicate/represent globally "always valid" actions (if such a concept even truly exists for REST)?

The meta question is, can you at all 'factor out' repeated hypermedia?

By simplified example, lets say we have a resource /version with Allow: OPTIONS HEAD GET. This resource depends on nothing and is NEVER affected by any stateful transitions that may occur elsewhere.

  1. Is the requirement that /version hypermedia are simply sent along with every single other resource request?

  2. Or the alternate pattern, with Client behaviour to link back to Home (likely cached) and THEN trigger our always valid /version call? (A "modal" pattern in GUI terms - close this resource, return home, and move on)

  3. Or is there some kind of method/pattern to create independent decoupled modules for any given application? (perhaps namespacing of some kind?)

In a complex, but loosely coupled API, option 1 ends up being buried in Hypermedia hell with 80-95% of your payload being repeated on each resource call. Which seems "right" but is so nasty. Option 2 leads to either strange quirks in GUI client behaviour (hiding valid elements until you 'return home' - modal type ops) OR lots of non-restful assumptions by the GUI client hardcoding out-of-band actions it "knows" are always valid.

Option 3 relates back to my initial question: is there a flag, or some other pattern for indicating globally valid actions that can be sent once (say with the root/home resource) and then "factored out" of subsequent responses?

2 Answers 2

2
+50

Well, there's a couple of things going on here.

First, you could simply add a link to any of your common "global" resources. As much as I am loathe to compare a REST architecture to a web site, a web site is a fitting example here. Consider many of the resources here on SO have links to common, "global" resources -- such as the home page, /questions, /tags, /badges, and /users.

The fact that a resource is "static" and never changes has no affect on whether you make the resource available as a link via another resource as part of HATEOS, that's an orthogonal issue.

The second point is that there is nothing that says the entire service be continually accessible from every resource. You can have "well known" entry points in to your service, and these can be well documented (externally). The only downside is that if the URLs for a certain relation changes (/questions to /questions-2, say), then those URLs may not be picked up automatically by clients. But this it likely not an issue, since by changing the URL you are likely changing something else (such as the payload) that affects clients to the point that an older client may well be incompatible with the new URLs.

Having clients "know" where things are in a nested system is not an issue either. For example, if they "know", as documented, that they can only access /version from the /home resource, and every other resource has a path to /home, (either directly, or indirectly), then this is not a problem either. When it wants /version, it should have an idea of what the path is to get it.

As long as the client is traversing the graph based on what you tell it, rather than what "it thinks", then all is well. If the client is currently processing the /blog/daily_news/123 resource, and it has a link rel to "parent" which has a url of /blog, and /blog has a link rel of "version" to /version, then the client can walk the graph (traversing the parent rel to /blog, and the version rel to /version). What the client should not do (unless otherwise documented) is that it should not ASSUME that it can visit /version whenever it wants. Since it's not linked from /blog/daily_news/123, the client should not just jump over to it. The rel isn't there, so the client "doesn't know".

This is the key point. The fact that it is not there means it's not an option right now, for whatever reason, and it's not the client task to force the point, as the URL space is not in its hands, it's in the services hands. The service controls it, not the client.

If /version suddenly vanishes, well, that's a different issue. Perhaps they timed out and aren't allowed to "see" /version anymore, perhaps you deleted it. The client at that point will simply error out "can't find version rel" and then quit. This is an unrelated problem, just a truth of the matter (what else can you do when resources suddenly vanish behind your back).

Addenda for question:

Which, if I understand this means: if /home is not expired, and we navigate to /blog (which contains a rel back to /home) then the rel methods at /home are still immediately "accessible" from /blog right?

No, not really. That's the key point. Save for some global resource specifically documented (out of band), you should not traverse to any link not specified in your current resource. Whether /home is not expired or not is not relevant at all.

The server could certainly have sent appropriate caching instructions, letting you know that you could cache /home for some time, but you should still traverse through the rel to /home to get any links you think are there.

If /home is well cached on your client, then this traversal is effectively free, but logically and semantically you should stick with the protocol of traversing the links.

Because if it's NOT cached, then you simply have no idea what rels will be there when you get back. Yes, 99.999999% of the time it will always be the same, and shame on the server for not sending the appropriate caching headers, but by definition, the server isn't promising you anything, so both you, the client, and it, the server, eat the processing costs of hitting an effectively static resource over and over and over again.

By mandating your client follow the steps, perhaps with internal optimizations due to caching and pre-processing to make these static traversals quick and efficient, you stick with the model of HATEOS, and defer to the system to make it optimal rather than pre-supposing at the code level and jumping through rels you think you already have.

This way your code will always work, regardless of what the server does. Who knows when they may turn caching on or off, your code certainly shouldn't care, not at the level of deciding whether or not to dereference a link certainly.

The premise of HATEOS is that the server is in charge of, and mandates its URL space. Arbitrarily jumping around without guidance from the server is off spec, it's not your graph to navigate. REST is for more coarse grained operations, but proper caching and such can make jumping through these hoops quick and efficient for you the client.

1
  • Which, if I understand this means: if /home is not expired, and we navigate to /blog (which contains a rel back to /home) then the rel methods at /home are still immediately "accessible" from /blog right? (ie. the graph of actions from /blog includes any on /home while /home is not expired)? Jul 25, 2013 at 3:25
1

Maybe I'm misunderstanding the question, but it seems like client-side caching should solve this. Look for the Expires and Cache Control headers.

1
  • I think this suggests something like Option 2? Whereby the client queries "a link back to 'Home' (likely cached) and THEN trigger...". This works, but requires navigation between states to re-access "globally valid" states (cached or not). If I wish to access my "global" /version from /foobar, as I understand it requires embedding the hypermedia for that resource. Boo. How to factor globals out? Jul 24, 2013 at 2:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.