.png){kind=small}
The internet is amazing
When you work in software you can get pretty blasé about the internet: it’s just something that’s there, like electricity and running water. We take for granted the fact that we can type some words into a laptop and those same keystrokes will whizz their way through hundreds of different machines owned by hundreds of different organisations, and pop out virtually instantaneously on another laptop on the other side of the planet.
It’s worth stopping to think about how this miraculous state of affairs came to be, and the answer is pretty mundane. Essentially a bunch of people around the world came together to agree on a set of standards by which telecommunications infrastructure and devices interoperate and communicate.
Standardisation is frustrating and slow, but it does work eventually, mainly as its collectively in everyone’s best interests. The internet is a global machine: even if you think you’ve worked out a really great solution to send bits from one bit of equipment to another, at some point those same bits are going to enter equipment that you didn’t build, and if you don’t agree on a common language you’re pretty stuffed.
What’s that got to do with APIs?
It would be nice if the various services that we run on the internet show the same kind of enlightened self interest when it comes to interoperation. When we build a service for customers, we’re managing their data, not ours, so it’s surely reasonable that they should be able to access and manipulate their data just as easily as we can in our apps, and that means using an API.
Unfortunately many companies seem to treat APIs as almost an afterthought: something to bolt on after the fact. They are often poorly documented, with inconsistent naming conventions and patchy coverage. I’m going to argue that this kind of sloppiness is a Bad Idea, both from an ideological standpoint and from cold hard business logic.
APIs should be open, extensive and accessible
Here at KisanHub we take our APIs seriously. For a start, our documentation is publicly accessible to everyone (check out https://docs.kisanhub.com). Of course you need to actually have an account with us to use the API, but we’ve no problem with you seeing it.
In fact we go further than most in making our APIs accessible. For a start, there is no such thing as a “private API” in KisanHub: every app that we build on the platform only uses our public API. There’s absolutely nothing to stop you building something equivalent to our desktop and mobile apps: knock yourself out. (Of course we think our own apps are rather special so don’t feel you have to do this, but hey, the option is there).
What - everything is public?
Apart from the afore-mentioned ideological point of it being your data not ours, there are good reasons to do this from a coding convention perspective. If you’re writing a “private” (or undocumented) API then you’re likely to cut corners with naming conventions and backwards compatibility.
If you write every API with the assumption that someone else could use it (even if they’re pretty unlikely to), then you will take extra care to ensure that your APIs make sense, have sensible naming conventions and are backwards compatible. It will also make you think very carefully about data security: if you bake this into your APIs from the start you won’t be relying on “security by obscurity”. Basically openness keeps you honest.
We’re unlikely to have a standards process for APIs apart from in some very specific domains (e.g banking), but by publishing your APIs in the public domain you will help the whole software ecosystem to up it’s game. This is exactly how open-source software works: the source code is public and anyone can tweak it, which means that good ideas and solid design tend to win out over time.
Document as you go
A natural corollary of this approach is that you absolutely have to document as you go. This is obviously a good idea: leaving your homework until the last minute never goes well. At KisanHub we use Open API 3.0 (i.e “Swagger”) specification to define our APIs, and build this into our development process: we write the specification and review it before we build it.
We use the rather lovely ReDoc library to auto-generate our documentation from the spec, which we then auto-deploy once the spec has been reviewed (here’s our QA docs if you’re interested). In practice this means that it’s perfectly possible to build the front-end code in parallel with the server code, as the front-end developers can simply mock out the expected response, safe in the knowledge that when the API is actually implemented their code will Just Work.
Developers hate PDFs
Well, I would assert that everyone apart from printer manufacturers hate PDFs, but developers have a particular aversion to them when they’re used for API docs. We live our lives online, and we are used to being able to easily search for information that we need.
If you use Open API and you’re happy with ReDoc then you can get it published for the cost of serving a few static files (i.e essentially free). If you want some more control over the look and feel then there are hundreds of SaaS platforms that will help you out there. There’s really no excuse for not having your lovingly crafted API documentation available on the internet.
Consistency wins
One of my favourite books on User Experience is Don't Make Me Think by Steve Krug. It’s a very short book, and the clue is in the title. Basically users shouldn’t have to think about how to use your product: it should be natural and obvious, and the trick to this is consistency.
Exactly the same points apply to API design:
Make sure you use the same naming conventions everywhere.
Be consistent and clear with units where appropriate.
Provide a glossary and stick to it. If you’ve changed your mind over time and come up with a better name for something, make it clear in the docs (and continue to allow the previous name for a while for backwards compatibility).
Re-use design patterns. For example all paginated endpoints should behave in the same way, and error reporting should be consistent.
Use hyperlinks. Your documentation is going to be online, and hyperlinks are kind of the whole point of the World Wide Web, so use them.
In summary
Your API is the public face of your code. If you work on any kind of client-server architecture (i.e basically everyone) then you’re writing APIs anyway, so you may as well take the time to do it right. Openness and interoperability gave us the internet we know and love: let’s see if we can do the same for the software that runs on it.
About the Author
Nick has been writing software for nearly 40 years, and oddly enough is still enjoying it. He's worked on an alarmingly diverse array of languages and platforms, but is currently playing with Python, Angular and DevOps automation with Kubernetes.