Search code examples
api-designhateoas

Is it HATEOAS compliant? GET same address with different results


Is it HATEOAS-compliant to expose resources via GET /resources when this call returns a different resource each time?

For example to distribute resources across clients, according to some internal algorithm, meaning I don't want every client to receive always the same resource (let's say I coded a 'phrase of the day' server and distribute them randomly):

First call: GET /resources

200 OK
{
  "_links" : { "self" : "/resources/1" },
  "data" : "foo"
}

Second call: GET /resources

200 OK
{
  "_links" : { "self" : "/resources/2" },
  "data" : "bar"
}

Or is it better to provide a GET /resources/chooser that returns a links object to the concrete resource and make a second call?


Solution

  • HATEOAS is about following links. So until you expose these operations (except getting the API root) as links with metadata (like "self" in your example), it is fulfilling the HATEOAS constraint. There is no standard about the URI structure, just suggestions. For example it is easier to route calls for named resources. Note that for the REST client the URI structure does not matter, because it checks the link metadata to decide whether it want to follow a link.

    In your current example the /resources should have a self descriptive metadata, for example rel=chooser or something like that. So the client will know what is it about. I think your URI structure violates the URI standard, because the path describes the hierarchical part of the URI, but in the current case there is no hierarchy between the /resources and the /resources/1, /resources/2 URIs. So if you want to create and alias or with your choice of words "chooser", it is much better to use the /resources/chooser or /resources?chooser=true.