Hacker News Reader

Comment by amyjess | Hacker News Reader

> no documentation is needed

I would not want to code against your API.

Did you read what I posted? If you're writing a REST API (I advise you to read http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... if you think you know what REST is) then all you need is an entry point (much like http://news.ycombinator.com) then everything else should be hypertext driven.

I know what REST is.

Congratulations, I now have a URL and a JSON file the URL spits out.

I still have no idea what the significance of all the values are. I have no idea what their possible ranges are. I don't know how everything works together.

Edit: Also, that's just GET. If you expect me to poke around with POST to learn how your API works, I will run far, far away.

So you don't know what REST is (and didn't read the link I posted earlier).

REST as defined in the original papers, REST as defined by your link, and REST as actually used in practice are all somewhat different.

Even in your link it is plainly obvious that there is no provision for documenting what an endpoint does, or how to find what endpoint maps to something, or even how to query this magical introspective API to figure out what further requests you need to make.

to be fair, you definitely seem to have some personal prescriptive definition that the rest of the world may not be sharing at this moment

It is not "personal definition". And I have shared it… just follow the link I posted earlier.

I admit, my central point was perhaps too subtle. I'll state it plainly: you are factually incorrect about what REST requires.

Everyone in this thread needs to up the civility and charity a couple notches. I think what's at heart here is a disagreement about what exactly is required by HATEOAS. I'd like to hear people expand on that.

Please educate me (and everyone else reading). What is incorrect?

Reply on news.ycombinator.com