Hacker News new | ask | show | jobs
by BetaCygni 4671 days ago
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?
1 comments
joeblau 4668 days ago
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...

link