I’m trying to clarify a concept related to REST discoverability – that is whether or not satisfying the HATEOAS constraint for a RESTful service means that now the URIs can change, because they are discoverable and not documented.
That seems to not follow the concept of Cool URIs – the fact that URIs don’t change, ever. It is also somewhat uncongruent with the model of the web itself (which REST should essentially fit perfectly) – the fact that URLs are bookmarkable and never change, and the fact that you once you learn one, you can go directly to it and you do not have to go through the root and discover it each time.
Any feedback on this is appreciated.
For Cool URIs, no – you should not change them, ever. They are the entry points into your system. However, you should have very few of those if you want to have the ability to evolve the rest of your system’s URI structure in the future.
For any non-Cool URIs, they can indeed change over time. I recently wrote a blog post about this topic because I find REST’s ability to allow me to evolve my system over time to be incredibly useful.
Make sure your API documentation spells out the fact that only the few Cool URIs in your system should be hard-coded by clients, and any other URI should be discovered at runtime through hypermedia traversal. Think of them like a C pointer address: nobody would care what the hex value of a pointer variable is, but they sure as heck would want it to point to a valid place in memory. Same goes for your non-Cool URIs – their structure doesn’t matter, but the fact that they were retrieved at runtime through conversations with your server makes them valid.