9

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.

Jakob
  • 2,588
  • 5
  • 27
  • 34
Eugen
  • 8,523
  • 8
  • 52
  • 74

2 Answers2

6

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.

Brian Kelly
  • 19,067
  • 4
  • 53
  • 55
  • Thanks for the quick response. I've read the article but I'm still not clear on a few things - first, isn't that what versioning the API is for? and second, should there be ANY documentation? My understanding is that in a pure RESTful implementation, there would be pretty much zero documentation. Would it be better to only use cool urls and do a different version of the API for such a sweeping change? – Eugen Nov 13 '11 at 11:31
  • 1
    Versioning an API purely to maintain URI structure compatibility leads to the same issues as having a WSDL for each version of your web service: you aren't evolving your service, you're adding new (mostly duplicated) versions of it each time which you'll need to test, maintain, document, etc. Do that, and say goodbye to a huge benefit of REST: dynamic evolution of your "contracts" and a wonderful decoupling of client and server. – Brian Kelly Nov 13 '11 at 18:14
  • And as for having no documentation, sure - when the entire software world has developed expertise with REST, it will make perfect sense. There will always be newbies wanting to use your API, and giving them nothing to work with makes no sense to me. Sure, a REST expert could probably sit down and figure it all out, but that's not the world we live in. Document your media types and the semantics of each resource and give sample code that shows how well-constructed clients should be built, and you'll be fine. – Brian Kelly Nov 13 '11 at 18:17
  • Makes sense from a pragmatic point a view. I was however thinking more in terms of a pure RESTful implementation, before the need to compromise. Relating to versioning and a pragmatic approach, I'm interested in a practical experience of an API that is indeed consumed by a large number of clients - can that actually be changed? Pragmatically my thinking is that it cannot, and that versioning is the only viable way to go, especially in the light of the fact that there are also other advantages to keeping cool urls. Thanks for the interesting feedback. – Eugen Nov 13 '11 at 22:15
  • 1
    I haven't seen a RESTful API that did evolve without versioning of URIs, and I think that's due to the fact that most programmers gravitate to the "contract-first" mindset bred by technologies like WSDL, CORBA IDL, etc. It is absolutely possible with REST to move away from that thinking, and I'd encourage you to try to do the same. – Brian Kelly Nov 13 '11 at 23:07
0

There has to be documentation. MediaTypes and Link Relations are a coupling point and both the client and the server must understand that. That's why HTML, ATOM and RSS have standards.

In terms of runtime functioning I can see not having documentation. I don't need to know what Yahoo has on it's home page because I can discover that. The same way a client of my service doesn't need to know about a new feature I release. They can find the link exists and then use the link relation to see what it does.

So the documentation is around the standards and protocol that are to be used, but not how the application will function itself

suing
  • 2,808
  • 2
  • 16
  • 18