Ask HN: What makes an API good?

I've consumed a great deal of major, public facing APIs over the years, some I've liked more than others. However, I'm writing a series of APIs for a new project, and ahead of starting I've documented the things I like about some APIs and things I don't about others. For example, uri construction, documentation, response time, flexibility, code samples and organization of taxonomy help me differentiate good and bad.

I thought I'd ask, what do you think makes for a good api?

Documentation.

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)

One vote for good documentation.

Not just a link to the Javadocs; preferably a "getting started" page that covers the most common use cases with plenty of plug and play examples (if such a thing is even possible in your case).

Also, getting back to the API reference, I'm grateful when there is a roadmap or overview of the class/package structure so I don't have to crawl through the entire thing.

I highly recommend this ~hour long talk given by Josh Bloch a few years ago, it is quite good and gives plenty of concrete examples: https://www.youtube.com/watch?v=aAb7hSCtvGw