[joeblau]

You are not the only one. I read though it, clicked around, looked at the demos, thought about bookmarking it, got to the documentation page and saw this `/api/v1/subscription/`, thought That breaks HATEOAS then left.

I'm sure if I put more time into trying to understand what is going on I could figure it out, but to me, the message isn't that clear.

[BetaCygni]

Did you actually use HATEOAS? I'm currently designing an API and it's just way too much work and overhead to add links when everyone is just going to hardcode them anyway. Do you have any examples where HATEOAS actually prevents or solves problems? Do you have any tips on how to get people to follow the links instead of hardcoding?

[joeblau]

The last API that I wrote used versioning in the headers and it saved us a ton of headaches when we updated our API. Our V2 upgraded some JSON fields of the API and our users who were on V1 were never affected. The funny the whole concept is that, you use it every day without even thinking about it. If you think about the web when you're looking at an PDF; What tells you if what version of the PDF file it is? Not the URL, it's the meta-data in the PDF tells you. You'll never see a link like:

  server.com/files/a-cs3/important.pdf
  server.com/files/a-cs4/important.pdf
  server.com/files/a-cs5/important.pdf

You'll see

  server.com/files/important.pdf

The information about the version of that pdf is contained in the document and managed document itself. What this allows for is you updating the PDF in any PDF editor without breaking how everyone else on the internet will process the file. You can edit the pdf with anything, re-save it and not break older version. This is the same concept that you should use to extend an API. If you think of the API as an document for a version of DATA (Just like any file/image is an endpoint), it will help you get a better grasp of why you shouldn't version in URL's.

Here is a more accurate description of the how you should design a REST API from the Author of the HTTP spec: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

[dscrd]

I'm interested since my application publishes URLs just like that. What's wrong with it as far as HATEOAS is considered? How would it be better?

[Kiro]

How does it break HATEOAS?

[sopooneo]

People argue that, with REST, versioning should be done in headers and not the url. Maybe that?

[steveklabnik]

Nooe, HATEOAS is about links. The official-sounding thing that this would violate is the "server should be able to organize its own namespace."

That said, I don't think this actually mandates any URLs. I read that part as just a suggestion for how it could be done.

[sopooneo]

Does that mean it should be possible to just have the link be "subscription"?

[steveklabnik]

It means that the spec shouldn't specify URIs, and instead publish link relations.

(I'm not saying that I think it should be that way, just elaborating.)