Saturday, December 17, 2016

What is an API for non-technical people

During conversations over the last few weeks, I have been asked more than once by non-technical people... "What is an API ?"

As technology evolves to have more interconnected systems, many will find the term API becoming a larger part of their lives. This includes both business people and technical people alike.

I thought I would share an analogy to help those that are less technical understand some simple concepts to get you started on your own journey of learning, or just to help you feel better when talking with someone about the topic :->

If you are interested in incremental, multi-team delivery, you will find these concepts important to understand.  

There are other concepts and the following is definitely an over-simplification, but this should get you started.  My goal is not to make you an expert, but to get you ready to have some conversations about this in your environment.






  • Public interface
  • Keep the implementation private
  • Don't make something public unless you really have to

For the purpose of this post, consider an Interface to be .... 

The means by which you interact with something to send and/or receive information or change of state.

An API is an Application Program Interface.  To extend the definition, consider an API to be...  

The means by which you interact with a Program or System to send and/or receive information or change of state.


For the technical people out there.. Yes, I know this is an oversimplification.




The Automobile gas pedal.

Public Interface - To interface is simple. One moves the pedal forward to increase the flow of gas to the engine.  Decrease the distance forward and the opposite happens.

The results are known to us either a - vehicle going faster, or b - engine revving faster, c - vehicle going slower, d - engine revving slower.

It is important to understand, there is no interface through the gas pedal for speed, torque or anything else.  Those are other systems that have their own interfaces.

Keep the implementation private - Imaging for yourself that to know how to push the gas, you needed to know

- How many cyclinders the vehicle has
- Is it gas or electric
- What size engine
- What type of engine computer
- etc.

If you needed these to interact with the gas pedal, it would certainly be more difficult to drive.

Imagine that before you pressed the gas pedal, you had to calculate the force necessary based on engine size, the angle of the hill you were on, figure out which cylinders to turn on in what order to be able to press the gas.

Don't make something public unless you really have to.

These details are referred to as Implementation details. A good interface keeps this information private (not visible to the person or system using it).   

By using this approach, you could for instance, change your engine from one type to another, or get an updated engine computer.  You might have different results as you press the gas pedal with evidence from other interfaces (ie: speedometer), but you didn't need to change anything in the current interface or learn anything new to use it.

Don't make something public unless you really have to - This concept is extremely important for those that are growing systems incrementally or organically. Think about it this way... 

Once you make an interface public in a complex system, it may be almost impossible to remove that interface from future iterations.

This situation will be compounded in systems that take years or generations to change or where interaction from other systems may rely on these interfaces long into the future.

In the example of our car, let's assume that someone said "You know, we could make the gas pedal really awesome if we allowed the operator to press on the right or left of the pedal by angling their feet to give a different acceleration potential".  

This might make sense in your environment (let's say you have a specialised product for race car drivers and that would improve their lives significantly!). Innovation is cool that way.

My goal here is to have you consider this; Would a different interface be appropriate ( a hand control for instance). Could we have a separate control for Normal Acceleration or Faster Acceleration (think about this.. some vehicles have a Sport Mode).

There are two potential considerations should you decide to add this really cool interface Publicly (in your current application).

In a distributed application or system, something or someone will use a public interface! This means that you may need to have that ability in your system forever. You may never take it away (well, not easily at least).

If you realize later that you should have made a different interface (Sport Mode), it will be too late. You have made the interface public.  


  • People may have already created driving schools for the new accelerator system
  • Someone may have created a special shoe to use it
  • Control systems may have been built to control the pedal from a manual control that converts it to suitable pressures on the gas pedal 
  • And so on.
To complete the analogy to software or systems development, now anytime someone wants to use the interface they have to spend time and effort learning and understanding acceleration concepts when all they wanted to do was press the gas pedal.

I hope this helped the non-technical person to be able to have some knowledgeable conversations about Application Program Interfaces or APIs.

There are Interfaces at different levels in your vehicle. Examples include....

- Engine computer
- Fuel pump
- Light switch controller
- Engine itself (think electric)
- Speedometer
- Tachometer

Technically oriented people will be using this term often in the future. APIs and discussions will become more prevalent as technology becomes more pervasive. The Internet of Things (IoT) is mostly about APIs for starters.

Hopefully, I have given you a bit of a non-technical description that helps you out to start your learning journey about this topic.

Actually, even communication and conversation is a form of Interface between humans. That's a topic for another time :->

Enjoy.