Author’s Note: This series is intended for a more general audience to understand broad concepts, not a how-to for developers. Although hopefully it is of use to developers to contemplate the nature of these terms too.

* * *

Have you heard the term "API" bandied about in technical discussion, not known what it means and were afraid to ask? If so, then this just may be the blog post for you.

For starters, it stands for "Application Programming Interface" but that doesn't help much on its own. The term can be a little confusing since it's not always used properly, and it can mean one thing in one context (e.g. web) and another in other contexts (e.g. within an operating system). Sorry, I don't think I've helped clear this up yet! Stay with me though. We're going to define it a few ways (including showing the excellent graphic above from www.govtech.com.)

My Definition

An API is an interface that software code can use to execute a command or retrieve a set of data. Hmm, I'm pretty sure I'm satisfied with that definition.

For as long as I've been working in software (22 years which can sometimes seem like 2 lifetimes in the industry), APIs have been around - and another 30 years before that. APIs are themselves software code which has been packaged up so other code can reference and have the API perform functions for them, but they are "black boxes" in that you never get to see the code in the API. You send it some parameters and you get back a result.

The ATM Machine Analogy

I once heard a great analogy for APIs: think of an ATM machine as an API. There are certain conventions about how you interact with it; you insert a card, they ask questions and at the end you can receive money and/or receipts. But you don't get to access anything about other people's accounts, you never get close to the vault, and it doesn't require a person at the bank to be typing back to you.

They are truly "black boxes" meaning if you use somebody’s API, you have no idea how the code works inside it - it might as well be magic.

Inherit Benefits Of APIs

Taking advantage of previous people’s coding efforts is obviously an incredible time-saver for all programmers, which is a huge advantage of APIs. Additionally, they create efficient standards.
That’s one of the core appeals of APIs: since somebody else has coded this, there's no reason for everybody else to replicate and duplicate efforts to write it again.

Secondly, APIs provide the most basic layer of security. If you're requesting data from API, you don't get a full copy of their database - you get what they (and the API) allows you to get.

Types Of APIs

Again, the context and usage of "API" seems to have changed over the years. At the risk of oversimplification, I'm going to break the usage into 3 major categories: Operating System APIs, Programming APIs and Web APIs (and we can dive further into them in future posts).

#1 Operating System APIs

These come installed when you buy your computer. Not only do these files compartmentalize the functions of the operating system (e.g. Windows) to make your computer do its most general tasks, the APIs can also be referenced and called from other applications on your computer.

You can have an Windows API tell you the width of the computer screen being used, the Windows logon name of the current user, or have it convert a lower case word into an upper case word - there are hundreds of thousands of commands available on your computer right now available through APIs.

Programmers can count on those operating system APIs being there; which is why Mac and PC each usually require a separate installation package with separate drivers, DLLs, etc.

(More details on these APIs here in Part 2)

#2 APIs Used In Other Applications

These are similar to operating system APIs. But those OS ones are built and installed by the maker of the operating system (e.g. Mircosoft) and are deemed necessary for the computer to run. This second class of APIs (by my definition) are for things beyond the operating system.

These APIs are either downloaded directly or, more often, installed by an application. For instance, once Microsoft Office or Office 365 is installed on a computer, there are dozens of Excel APIs now available for other apps to use.

Using my "An API is an interface that software code can use to execute a command or retrieve a set of data" defintion, when I use an API in one of my applications, I’m getting to "execute a command" that somebody else has written and embedded into their API.

(More applications APIs here in Part 3)

#3 Web APIs

This is probably where you hear "API" mentioned more often lately. You may have also heard the term "web services". APIs and web services are pretty similar. Just like APIs, if I call a weather web service, I might supply the city and get XML (formatted text) results of the next 5 days of high and low temperatures (whatever the web service has defined as the return results). That's a web service.

In its own way, it’s also similar to a "feed" defined very well here by ComputerHope "A feed is a program or a page that provides another program with information automatically. For example, a news website may have an RSS (Really Simple Syndication) news feed that provides the latest news headlines to another program or page."

Just for clarity, all web services really are APIs, not all APIs are web services. Also, "web" services happen over the web - that could still be within a network, but let's just say they are in a spot where you could hit them in a browser (being hosted like a web page is hosted).

Since it might help you further grasp the whole concept of an API, let’s have you look at a real-world example of a web service (aka API) results with this link where I supply an argument to the public National Highway Traffic Safety Administration website with a VIN number for a BMW and here are the results from NHTSA.

To really hammer home my definition of an API ("An API is an interface that software code can use to execute a command or retrieve a set of data"), in most web APIs we are using them to retrieve data.

(Read about web APIs here in Part 4)

The Takeaway, What This Means To You

I most often ever mention "APIs" to clients as saying one of the following:

1) There are available APIs for me to use to complete an application project quicker so it's standard and saves me a lot of coding (some of which I wouldn’t even be capable of doing without extensive documentation and a lot of time)

2) As a plan for where we will retrieve data; for instance, if we want to repost NBA basketball scores, we'll hit the "API-NBA" web service

3) Perform full functions for us, with an example being using PayPal or Stripe web services as a way to collect payment on a website.

We'll continue to write further about both programming apps to use APIs and using web services / APIs in website in the near future.

In the meantime, hopefully your eyes won't glaze over when somebody suggests that you need an API to accomplish what you want. Bottom line: APIs good, reinventing the wheel bad.


Continue reading Part 2 - Operating System APIs)