Hacker News Reader

Comment by freework | Hacker News Reader

As an experienced developer who as had to implement dozens of API's over my career, therre are two things that I care about:

1. Documentation - If I have to spend the next month doing trial+error to get your API working, thats no good. The best APIs have a page that describes how get up and running quickly.

2. Good error messages - When something goes wrong I want to know what went wrong. The error message being in a consistent format isn't that important, as long as there is a description of what happened. "Oops, an error occurred, try again later" is not a good error message.

Most of the stuff in this article is superficial stuff that I don't think matters.

View on HN

Better documentation is a non-trivial example application that, one, exercises all "normal" uses of the API, and, two, shows what the API developers consider to be best practices, all the way through.

Let me into your minds. Show me how you think I think. If you don't know how the people consuming your API think, your API is going to be pretty bogus. If your way of thinking is inimical to me, fine and dandy. Just give me a reasonable way to find out which isn't reading hundreds of pages of Javadoc or similar.

And if the example contains copy-and-pastable code, or reusable functions, so much the better. Make the licenses align, even if the code which implements the API is fully proprietary, and things will work out just fine.

Oh, and if you can't keep your example code working, that says something I need to know, too. Something nasty.

All too often we'll receive a "specification" document which just lists a bunch of URL fragments with the word GET or POST next to them. If we're lucky, we'll get a sample of the request and response body.

What we're left with are the two problems you described. We have no idea how to actually _do_ anything with the API. And when things don't appear to work, we're left guessing.

Some of the best API "guides" are the ones that break things down by use case and describe how to achieve it. For example, I'm a fan of GitHub documentation: https://developer.github.com/v3/issues/#create-an-issue.

Most of the stuff in this article is superficial stuff that I don't think matters.

What the article seems to describe are practices that generate consistent, predictable RESTful APIs, which is exactly how you yield easy to use APIs. This saves both the creator and consumer's time, as debate and decisions over deviations are avoided.

I'm not quite sure why so many comments have gone so negative -- this is hardly a revolutionary piece, yet many of us are creating or dealing with APIs that could do well to take some advice.

Reply on news.ycombinator.com