What is an API?

In my current job, I’ve had a lot to do with our product’s Application Programming Interface (API) – namely documenting it. For those of us who live in the technical world, we’ve dealt with APIs for many years and take them for granted. However, for those who live outside the technical world, an API is just another techie-TLA. The documentation with any API tells us how to use it, but not fundamentally what it is.

So here is my attempt at a simplified, non-technical analogy of an API.

Imagine, if you will, a puppet. We want to make the puppet dance. To do this, we grab the puppet by the arms, lift it, and make it perform a dance. This is akin to controlling a product (the puppet) through its native User Interface (its limbs). In other words, it is controlling the puppet using the bits that the puppet-maker made.

However, there comes a day when we want to control the puppet using two wooden sticks in the shape of an X.


Why would we want to do this? Well, for a start, it gives us a lot more control over our interface to the puppet. Because we have direct control over the sticks, we can customise them to fit our hands perfectly. We can paint the sticks any colour we want without affecting the puppet in any way. We could, if we wished, connect the same part of the stick to both the right arm and the right leg, meaning that these limbs would both move in unison with only one twitch of our hand.

This allows full control over the look and feel of the controlling interface.

With this in mind, we design our two sticks in the way that makes them a perfect fit for our hands. This leaves us with a puppet, and a controlling interface. All we have to do now, is hook them up.

With what does one connect a puppet to a stick? String, of course.

These strings allow for the movements made with the wooden X to directly control the movements of the puppet. And, as mentioned above, those movements can be customised, depending on where and how one ties the strings.

So a standard product (the puppet) is being controlled (via string) from a customised interface (the two sticks).

In this case:
– the puppet is the underlying product/program.
– the sticks represent the interface – designed, built and customised by you, the user.
– the strings are the API – they are what connect the controlling interface to the underlying product.

The end of a string is a somewhat generic connector. In other words, strings can be connected to almost anything. They could be tied directly to your fingers, meaning you’re the only one who can control the puppet; they could be tied to some kind of robot, which could make the puppet dance automatically; they could be tied to the two sticks, and those sticks can be given to anyone (or anything), allowing control of the puppet by whomever has the sticks.


This is the same for an API. The API allows a custom interface to control a product using a generic/standardised method. This allows for the control of a product from a custom-branded portal/interface. The interface designed by you can be an intuitive interface for your customers’ needs, saving you the cost of developing the underlying product.

It opens up a whole new layer for user experience design – one that does not need to involve creating an actual product. If the product is good, and can be controlled via an API, then there’s nothing to stop you adding value through a more intuitive interface. This allows the product’s developers to concentrate on the core product, while you can create the interface. And, as Apple has shown, a good interface can go a long way.

Moreover, it opens up an easy route for partnerships between technical companies. A customer might want a whole solution, but the best companies might be the best because they have concentrated on one specific area (“core competencies”” and all that). Using APIs, an interface can be developed that will use the best products out there, and seamlessly integrate them via their associated APIs. This is a win-win situation – the customer gets the best products, and the companies get sales.

So, hopefully, this will demystify APIs somewhat for those from a non-technical background. They are simply a means to attach one’s own controlling interface to a product, allowing for custom designs and/or automation.

All that you need to worry about now is checking that the underlying puppet isn’t Pinocchio, about to develop a mind of its own and not obey the strings.

  1. Holger said:

    Thanks Jamie, make things a lot clearer for us “normal” people!

  2. Good blog Jamie, it all makes sense now! thanks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: