Ask HN: What makes an API good? • Hacker News Board

ripberge wrote: post #34

I think it depends upon the use cases of the API, but if you want someone to be able to build snappy and fast "apps" using your API rather than just facilitating movement of data in/out for an integration with another piece of software, I think granularity is important. Having built our front end using AngularJS, we are the first users of our own API and that has driven it's design. In order to make things quick, we…

Sounds like you're going in the wrong direction. An undocumented, granular API with lots of options won't be used, so it won't matter how fast it is.

Re: Ask HN: What makes an API good?

#54

Post by angdis » Tue, Oct 28, 2014, 5:00 PM UTC

valarauca1 wrote: post #14

1) URL construction: KISS (Keep It Simple Stupid), or as Einstein said, "Everything should be made as simple as possible, but no simpler." 2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation. 3) Response Time: meh. If your at or around 100ms you…

Yes, examples are critical. It is possible, however, to make the examples TOO simple. I've seen this a lot in the documentation for libraries in the programming language R. The examples are so stripped down and abstracted from what you would use in actual work that you can't see how to apply them in a useful situation.

Re: Ask HN: What makes an API good?

#55

Post by jgrodziski » Tue, Oct 28, 2014, 5:17 PM UTC

There was an excellent talk at the last QCon New-York conference about good API design: http://www.infoq.com/presentations/API-design-mistakes Worth watch it in my opinion :-)

Re: Ask HN: What makes an API good?

#56

Post by ironcrucible » Tue, Oct 28, 2014, 5:18 PM UTC

sergiosgc wrote: post #42

1. Documentation. It has been said in other comments. If you do nothing else right, do documentation. It is paramount. Documentation must contain code samples that can be ran without scaffolding a huge project. cURL command lines -- or the equivalent in non-HTTP APIs, are, for me, as good as it gets. 2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be speci…

> 2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable.

This is something that I had to deal with just last week. I had been integrating a 3rd-party API into a business application, and it had very poor error handling and error descriptions. It wasn't even consistent on when an endpoint would throw an exception or just return some JSON with an error message.

To make things worse, I kept running into the same generic error message: "Something went wrong. Please contact support at support@example.com if it continues". Of course, that kind of error message doesn't help their support team, so they could only guess as to what was going wrong. We finally figured it out after several hours of guessing.

What's strange is that this was an API for a moderately popular Silicon Valley startup that's marketed to and primarily used by developers.

Please, if you're building an API, don't write these generic messages!

Re: Ask HN: What makes an API good?

#57

Post by jmakuc » Tue, Oct 28, 2014, 5:28 PM UTC

Be strict with your output and promiscuous with your input.

Re: Ask HN: What makes an API good?

#58

Post by smandadi » Tue, Oct 28, 2014, 5:36 PM UTC

notjosh wrote: post #5

Documentation is 1000x above anything else. This includes sample project(s). Documentation is without question the deciding factor of whether I'll use a service. Besides that, I care about support channels, adherence to standards (i.e. correct HTTP status codes), and as few hoops as possible to jump through to start (i.e. a curl command to get my auth key, and away I go)

How much documentation did you get, when you got your Mercedes Car. The stress on Documentation is a little overrated in my humble opinion. If the Tools are made intuitive and the API is made as a natural way of thinking and progression of the state of the Message, The API speaks for itself, and the Developers engagement would be at its peak. If you have to read a Documentation before applying your Brakes on a car, you might as well be too late. Adherence to Standards and not letting unexpected happen and get out of the way of the developers work process is the way to go.

Having said that, If you are on the leading edge of software which no one has attempted before, or trying to create a Market, Thats when your Documentation would explain those edge cases better to gain appreciation of your point of view.

Re: Ask HN: What makes an API good?

#59

Post by nbaleva » Tue, Oct 28, 2014, 5:44 PM UTC

bvanvugt wrote: post #15

Agree with notjosh on this -- so what makes documentation good?

In terms of documenting api's, Swagger is your friend : https://helloreverb.com/developers/swagger

Re: Ask HN: What makes an API good?

#60

Post by ripberge » Tue, Oct 28, 2014, 5:48 PM UTC

theblueadept wrote: post #53

ripberge wrote: post #34

I think it depends upon the use cases of the API, but if you want someone to be able to build snappy and fast "apps" using your API rather than just facilitating movement of data in/out for an integration with another piece of software, I think granularity is important. Having built our front end using AngularJS, we are the first users of our own API and that has driven it's design. In order to make things quick, we…

Sounds like you're going in the wrong direction. An undocumented, granular API with lots of options won't be used, so it won't matter how fast it is.

So this is why I said it depends upon your use case. We are an enterprise software company and there are probably less than 50 potential customers in our target market that could ever use the API.

We are one of the only companies that actually has an API. If a customer has a use for our API they'll get personalized support.