Should HATEOAS API client not use bookmarked URLs?

Question

Suppose I want to write an application that displays some prices of products. I discover a link using hypermedia which is a HTML form that takes product name as an input. I bookmark it and proceed to embed that link into the client.

Is there a reason why HATEOAS client should re-discover that resource (and underlying forms) again instead of using bookmarks?

Aren't those URLs supposed to remain intact (including form semantics)? Is it less work to rediscover newly evolved API (and guarantee compability) than to keep the old one working?

Answer 1

HATEOAS is not a spec, so there's no hard rule what should be done.

I think a best practice for a client would be to use bookmarks only for as long as resource these URLs were from is fresh.

For the server the best practice would be to keep old URL schemes working, and redirect old URLs to the new ones if necessary.

Answer 2

In HATEOAS, URIs are discoverable (and not documented) so that they can be changed. That is, unless they are the very entry points into your system (Cool URIs, the only ones that can be hard-coded by clients) - and you shouldn't have too many of those if you want the ability to evolve the rest of your system's URI structure in the future. This is in fact one of the most useful features of REST.

For the remaining non-Cool URIs, they can be changed over time, and your API documentation should spell out the fact that they should be discovered at runtime through hypermedia traversal.

Answer 3

Think of bookmarking as caching the URI. You cannot be sure that your cache contains the actual URI. You cannot keep that URI too long or you need to check if it is not 404. In the latter case you can try to rediscover it. I don't think rediscovering is always possible or worth the effort. E.g. if you find the URI by pagination and it was on the 1000th page, then the cost of rediscovering it is high unless you save the page number, which can change ofc... I think you need some sort of bookmark service for those cases. E.g. you can give the params you passed to the URI template and the resource type or you can give the old URI to that service and it should return the new URI. I don't know what is the ideal solution for this.

later:

Meanwhile I discussed this with REST experts, but we could not agree on the right solution. They proposed the sunset header or the deprecation header, but both tell the client that the resource will be removed. I think that is not the case here, because we keep the resource and only the URI changes, so in our case the resource will be moved. We have a 301 moved header for that and we can used redirection. I think after a while we can change that to 404 and add an error message that the URI changed. Later we can remove the path and return with 404 without explanation.