Hallmarks of a good API

Let's dig into an API. An API can be an HTTP API, but it can also be a software library, or CLI. I think there are many things which can make an API good or bad, but a few things come to mind fo rme.

In general, I think of the consumer. Who's going to use this API and how do I want it to appear to them? If we're being entirely honest, I've made a lot of good APIs but always with help. With feedback from others and help refining my design. It's not something I can easily do.

So I write some APIs, but more often, I consume APIs, so I can tell you what's important to me.

Documentation. An API has to be documented thoroughly and clearly. I really like Github's REST API and I use it often as a standard for how I think about REST APIs. Every action is thoughtfully documented with example requests and responses. I'll plug Readme as a good system for documentation, if you need one.
Breadth. Can I do all the things? If I can get only 90% of my app working using an API and have to do workarounds to get everything else done, then the API feels a bit lacking. It makes things that much harder, and it makes my app less resilient.
Consistency. An API should use the similar parameters and conventions. If it uses path.to.thing in one call it should not use path/to/thing in another call. I've seen a few command-line tools break that, and it always sends me to the documentation. I should be able to guess how some API calls should be.
Standards. There are API standards. For HTTP REST is a good standard. It sets some reasonable expectations and guidelines for everyone.
Errors. Errors should be clear and instructive. I really enjoy working with React because when there's an error, I usually know where in my code to fix it, because the errors are fairly instructive.

Further Reading