How to talk about APIs

One of the more challenging aspects of working with APIs is that outside of your own little tech bubble, nobody actually knows what an API is. Despite being hopelessly dependent on APIs for their day to day lives, when I tell my parents I work on an API they don’t have the slightest idea what I’m talking about.

There are a few reasons for this: first of all, despite all of us being hopelessly dependent on thousands of APIs to live our lives they have yet to enter the public consciousness, even as a vague computer-related term.

However the biggest challenge faced when talking about our APIs to the uninitiated is that you can’t see APIs, you can’t touch them, you can’t point at them and say “There, that’s an API right there!”. Even Wolfram Alpha can be loaded up and shown to someone and the most technophobic person will at least get the idea that it’s a website for doing Maths or something. That doesn’t work with APIs.

Talking about APIs

So how do you talk about APIs to the masses of people who have no idea what they are? You’re going to have to do it – you’ll need to talk to your non-technical colleagues about it, many of whom you’re entirely dependent upon to improve your API or get it out to the masses; there’ll be potential customers out there for whom your API is the exact solution to the problem they’re having and of course there’s your poor befuddled parents who just want to know what it is you spend your days working on.

The mistake we make is that as technically minded people talking about APIs we have a tendency to start with the technical detail of what an API is – one computer system talking to another, exchanging data, HTTP requests, how easy it works with Node or Java or .NET, open standards, RESTful interfaces and myriad other true but ultimately irrelevant bits of detail. It’s like explaining what a cookie is by describing stomach acids dissolving chocolate chips – while true, it’s not the reason anyone bought the biscuit.

The Answer

The answer is to talk about the common denominator about the your API that anyone, regardless of technical background, can relate to – the real world impact of using that API and how people benefit.

Intel faced this problem in the early 90s when trying to sell Intel chips to a public that had no idea what CPUs were and would never see them, they solved it by boiling down all the complexity of CPUs, bit ranges, registers, instruction sets, efficiency, cooling, energy management to a simple message: Intel chips make your PC faster. They were talking, in the most simple possible terms, about the real-world impact of using their product and leaving aside the massive complexity of how it works.

People use the Skyscanner API to find out the price and availability of flights at a given time, people use the Flickr API to automatically find relevant images to go with their articles, people use the Cronofy API to organise people’s schedules and the bookable resources for their organisation.

It doesn’t matter who you’re talking to or what API you’re talking about, the real world impact of the API should always be the first thing you talk about because it’s the only thing that really matters.

Of course we still love to talk about RESTful principles, how well an API works with this language or that, versioning or security but what we’re really talking about there is making it easier and safer for people to realise the real world impact of our APIs – we’re talking about the how it works and not what it does, which is fine, just don’t lead with that.

So next time someone asks you what your API is, don’t tell them what it is, tell them what it does.

‍