Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

An API is only as good as its documentation

rocketeer.be

Post reply on HN
Print view View original

41–50 of 59 posts

Re: An API is only as good as its documentation

#41

Post by gtramont »

amyjess wrote: post #35
gtramont wrote: post #33

Earlier quoted context omitted.

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

Re: An API is only as good as its documentation

#42

Post by oldmanjay »

gtramont wrote: post #41
amyjess wrote: post #35

Earlier quoted context omitted.

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

Re: An API is only as good as its documentation

#43

Post by gtramont »

steveklabnik wrote: post #40
gtramont wrote: post #27

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.

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_ documentati…

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

Re: An API is only as good as its documentation

#44

Post by Erwin »

pksunkara wrote: post #16
micahasmith wrote: post #12

Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger ( https://api.print.io/docs/ ) and "self-documentation" ( http://print.io/api ) but i still find that we have a lot of questions.

You can try using API Blueprint ( https://apiblueprint.org ) which is based on Markdown can host your API docs at http://apiary.io Disclaimer: I work at Apiary

For our corporate API, we the Apiary markdown with aglio to convert into nice documentation. I've tried RAML (I didn't like the giant YAML file) and apidoc (I didn't like to put 100 lines of user documentation next to 20 lines of implementation). I use protagonist to convert the md file to JSON which my Python code can load and compare with the decorated API endpoints -- I can then verify they and all their parameters are properly documented. I don't use the fancy Apiary features yet.

Re: An API is only as good as its documentation

#45

Post by gtramont »

oldmanjay wrote: post #42
gtramont wrote: post #41

Earlier quoted context omitted.

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.

Re: An API is only as good as its documentation

#46

Post by timjones »

micahasmith wrote: post #12

Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger ( https://api.print.io/docs/ ) and "self-documentation" ( http://print.io/api ) but i still find that we have a lot of questions.

Definitely check out http://readme.io. Their docs look beautiful and set-up is a breeze.

Re: An API is only as good as its documentation

#47

Post by oldmanjay »

gtramont wrote: post #45
oldmanjay wrote: post #42

Earlier quoted context omitted.

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.

Re: An API is only as good as its documentation

#48

Post by gtramont »

oldmanjay wrote: post #47
gtramont wrote: post #45

Earlier quoted context omitted.

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?

Re: An API is only as good as its documentation

#49

Post by dllthomas »

oldmanjay wrote: post #47
gtramont wrote: post #45

Earlier quoted context omitted.

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.

Re: An API is only as good as its documentation

#50

Post by goatandsheep »

wantab wrote: post #9

I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them. For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you'…

I always use archive.org to archive links so that if they break, I can always link back to them later.
Post reply on HN