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

Here's some examples of me using other APIs:

• Github REST API to handle complex deploys at Pinterest.
• A retweeting robot using the Twitter API.
• The Github Actions API for build triggering.

Not an exhaustive list, but this is what I want out of APIs.  How about you?  Send me an email at apis@davedash.33mail.com.