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

11–20 of 59 posts

Re: An API is only as good as its documentation

#11

Post by onion2k »

BetaMechazawa wrote: post #5

I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?

It's really not even close to being verbose enough. A good API doesn't just give you the name of the endpoint and what it's expecting - it should explain what the endpoint is for. Your documentation assumes the user already knows what they're going to implement in terms of your API (eg they know that they'll need to create a 'service' that other clients will 'listen' on, and so on.

Also, what's especially unhelpful in your documentation is the fact your example code returns errors. In the /listen POST documentation clicking the Send button displays

  {
    "error": {
      "id": 4,
      "message": "Already listening to that service"
    }
  }
I assume that means it's already connected, but should that be the case in an example of creating a connection?

EDIT: My post would be more useful with an example of how verbose I think you should be. Firebase gets it right - https://www.firebase.com/docs/web/quickstart.html - and their brilliant interactive tutorial that really drives home how easy it is to use - https://www.firebase.com/tutorial/#gettingstarted

Re: An API is only as good as its documentation

#13

Post by shivang »

A very valid point raised by the author. Having worked with multiple api's i can say that developers start preferring that product which has better api docs than the other product which has a crappy doc inspite of having many features.

I was working with PayPal few years back and there are bunch of apis that they provide, but the explanation and usage is so bad that you end up spending a lot of unnecessary time figuring out what to do. And then i came to Stripe integration. They have beautiful apis which can be integrated smoothly and very easily. I tell developers to follow Stripe's api for writing documentation and examples.

Re: An API is only as good as its documentation

#14

Post by BetaMechazawa »

onion2k wrote: post #11
BetaMechazawa wrote: post #5

I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?

It's really not even close to being verbose enough. A good API doesn't just give you the name of the endpoint and what it's expecting - it should explain what the endpoint is for. Your documentation assumes the user already knows what they're going to implement in terms of your API (eg they know that they'll need to create a 'service' that other clients will 'listen' on, and so on. Also, what's especially unhelpful i…

The API documentation is talking to the live version of the application. The pre-filled variables can be used for quick testing but this also means that when you make the default user (UUID) listen to the default service it will tell you that it's already doing that. Changing the UUID should be sufficient to give it a non-error response for that API call.

I'll add some documentation about what endpoints do and what kind of "flow" an application needs to interact with the API when I get home from work. I'll also finish my quick start guide while I'm at it then.

Re: An API is only as good as its documentation

#15

Post by raus22 »

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.

e.g. http://docs.themoviedb.apiary.io/#reference/collections/coll... where TMDB use apiary, and with quick examples with the different inputs and outputs. So you can test it out right away WITHOUT needing to find ID's to use for test. This provides real response values, as to know what you get when you send some value.

Re: An API is only as good as its documentation

#16

Post by pksunkara »

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

Re: An API is only as good as its documentation

#18

Post by BetaMechazawa »

yourad_io wrote: post #10
BetaMechazawa wrote: post #5

I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good. It requires javascript for the "full experience". https://api.pushjet.io Should I redo it? Are there things I should change?

I would add a few paragraphs introducing it and giving some common examples/use cases. I like your "try-this-request", however IMHO it is missing a "request is in progress..." kind of indicator - clear the output space and add a spinner? I had to look in the developer tools to ensure that it works. Finally, not all things work: 'Websockets/Run Example' doesn't do anything. In the background there is a 500: 'WebSocket…

Thanks a ton! I've always been annoyed by the fact that Web API documentations never had a "try-this-request" feature. I'll get right to expanding the documentation when I get home like I said in the other comments. The request in progress indicator should be pretty easy to add. Totally forgot about it. I disabled the websockets example because It's currently undergoing a complete rewrite.

Re: An API is only as good as its documentation

#19

Post by illumen »

rubenv wrote: post #4
pavlov wrote: post #2

I have a corollary of sorts: A framework is only as good as its UI. This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too. Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.

Absolutely, tooling is a hugely important in making or breaking any programming language/framework. In the end it all generalizes to "Your product is only as good as its experience".

You can have a lovely time using an API, and it could provide you results 56.786% worse than the competition. But you'd be happy, and not care.

Re: An API is only as good as its documentation

#20

Post by rprospero »

pavlov wrote: post #2

I have a corollary of sorts: A framework is only as good as its UI. This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too. Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.

I find your comment about Rails facinating, as it teaches me a bit about how I'm a Blub programmer.

I've tried to learn Rails multiple times and the "generate" and "console" commands have always been a massive stumbling block for me. With ever other language and toolkit I've ever worked with, the tutorial starts with opening up a text editor, writing some code, and producing a lousy, "Hello World" website. With Rails, I went through three pages of the tutorial before I even saw a single line of Ruby. I grew to hate the "generate" command, as it produced ever expanding reams of unexplained code each time the tutorial had me call it.

I had always assumed that the elimination of the need for commands like "generate" would be the top priority of the Ruby community and that their existence was a recognized design wart, like Python's GIL or Haskell's unsafe prelude. That "generate" would actually appeal to someone is something that I'd never even considered. That makes me a Blub programmer and tells me that there's another whole philosophy of programming that I need to learn about.

Post reply on HN