Hacker News Reader

Comment by gtramont | Hacker News Reader

It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.

View on HN

The problem with this "no documentation" stance, as you've seen below, is that it doesn't get the correct message out to those who haven't studied hypermedia.

I like to make an analogy to RSS: If I told you, "Here's a link to my RSS feed." You wouldn't be mad at me for that, since all you need is RFC 822. By the same token, hypermedia/"real REST" APIs don't have _no_ documentation: they have no _specific_ documentation about _this_ particular API.

Without a foundation in this approach towards building and consuming APIs, "no documentation" sounds like a disaster. And it is, in that context.

My premise was, when I wrote the first post, that REST is understood. Not a surprise that it is not…

I totally agree with you… And what I've been trying to do to whoever I talk to, in my team and outside, is to educate them in this area (sending resources like I did on an earlier post), and try to make them not call any json-based API REST (which in fact has nothing to do with json specifically).

> 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).

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.

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

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.

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.

Such a RESTful API will be much more difficult to develop than an RPC API + up-to-date documentation.

Reply on news.ycombinator.com