An API (Application Programming Interface) is the gateway to your application and data.
It’s the path by which an ecosystem and grow and evolve around your product offerings.
Or wonder why they even bothered.
That last line might seem harsh, good, it’s meant to be. API design is not a trivial endeavour as you are no longer thinking about how the team inside of the company will access your software, but rather how the entire planet will access and consume your information.
If you are designing an API, here are some guidelines to help in that endeavour.
- What is our core functionality? Are we going to expose it? If the answer is No to any of these sets of functionality, it’s important to then ask yourself why you are building the API if not to expose this core set of functionality that people use. For instance, if you are invoice taking software, chances are, people want to create, read, update, and delete invoices from your API.
- How will we make it available? Will it be exposed publicly but hosted by your organization? Will we use our own framework or something publicly accessible? Your own framework might be really slick, but if it takes two weeks for someone to learn how to use it, you’ve lost the value of your API.
- Encapsulate complexity – see #2, keep it simple, keep it asynchronous, keep it flexible. But don’t ask a user to chain 17 different events together simply to login.
- Provide examples and documentation – otherwise, you’re not writing an API, you’re writing a blackbox and putting into a test group to see what they can do with it.
There are probably more things to add to when writing an API, but at the top level, this is what has always jumped out at me.
