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.thingin one call it should not use
path/to/thingin 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.
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 email@example.com.