3 ms·
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 hype
by gtramont 12y ago
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.
- amyjess 12y ago> no documentation is needed I would not want to code against your API.
- gtramont 12y agoDid 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-hypertext-driven 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 http://news.ycombinator.com) then everything else should be hypertext driven.
- amyjess 12y agoI 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.
- gtramont 12y agoSo you don't know what REST is (and didn't read the link I posted earlier).
- oldmanjay 12y agoto be fair, you definitely seem to have some personal prescriptive definition that the rest of the world may not be sharing at this moment
- gtramont 12y agoIt is not "personal definition". And I have shared it… just follow the link I posted earlier.
- oldmanjay 12y agoI admit, my central point was perhaps too subtle. I'll state it plainly: you are factually incorrect about what REST requires.
- gtramont 12y agoPlease educate me (and everyone else reading). What is incorrect?
- dllthomas 12y agoEveryone 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.
- angersock 12y agoREST 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.
- steveklabnik 12y agoThe 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.
- gtramont 12y agoMy 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).
- dongliu 12y agoSuch a RESTful API will be much more difficult to develop than an RPC API + up-to-date documentation.