What is an API?


11 min reading time

Diagram of Computer, API and person

A beginner's introduction to APIs, what they can do, and why they're driving their own "API economy"

What does API stand for? Application Programming Interface.  You’ve probably heard the term before in one context or another. Maybe from a web developer friend, or in an article on TechCrunch. Something about connecting data, right?

This article is for anyone who’s ever wondered, out loud or in secret – just what exactly is an API?

Le Wagon: APIs for Beginners

Le Wagon logoLuckily, there’s Le Wagon. Geared towards creative, non-tech people who want to bring their product idea to life, Le Wagon offers a 9-week intense coding bootcamp in a handful of cities around the world.

Their instructor Thomas Sertorio went through all the necessary basics in their latest event, APIs for Beginners, much of which is summarized below:

What is an API?

Neither animal, mineral nor vegetable, the first thing to grasp about an API is: it’s an interface. An interface that gives access to what? To applications1. And what uses APIs? Computer programs do. This is an important point – APIs are directly used by programs, not humans.

So, for a clear API definition: an API is an interface that computer programs use to interact with an application.  Or as our Engineering Manager Philippe says, “APIs let computers talk to each other.”

Diagram explaining what an API is

Image from https://zapier.com/learn/apis/chapter-1-introduction-to-apis/


Don’t be tempted to confuse an ‘API’ with hardware. As Brian Cooksey from Zapier explains,

It helps to remember that the API is simply another program running on the server […] Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it.”

To put it another way, we could use the reasonably accurate analogy of someone using their hairdryer.  For your hairdryer to work, it needs electricity.  You aren’t yourself going to put your finger in the socket and withdraw the electric current – not only would this not help you dry your hair, you might end up electrocuting yourself.  You need an interface, something that’s going to make that electricity accessible and usable. Enter the socket.

But again, you aren’t going to put your finger in the socket, either – you’re going to put the plug of the hairdryer in it.  That plug will, thanks to the socket, extract electric current to power the hairdryer you’re going to use.

In this analogy, you are an average person using your computer. Your hairdryer is the computer program, the socket is the API and the electric current is the application.  “Drying your hair” is whatever the computer program was designed to do.

Some API Examples

So, let’s see some APIs in action.

Imagine you’re a content manager at TimeOut (a website that lists tourist activities to do in any given city).

For each event you list on TimeOut.com, you want to include a Google map with a little pin indicating the venue where the event is taking place. Now, you have a few options here:

  1. You can manually go to your atlas and look up the longitude and latitude of each address, and somehow use those to plot your address on your own
  2. You can ask your company’s web developer to write a specific line of code for each address you have
  3. You can use a program that will, using Google’s Geocoding and Javascript APIs, both fetch the necessary longitude and latitude from Google’s database and then plot them on a Google map directly integrated on your website in a matter of seconds

Option 3 is definitely the least labor-intensive, and the only one a reasonable person would use.  Let’s look at what happens when we try this:

Example of TimeOut back office form

Slide from Le Wagon

Our imaginary content manager enters an address to plot in a form in their back office – let’s say 10 Downing street.

Hitting “enter” sends tiny information packets, probably first via wifi and then through physical internet cables, all the way to Google’s servers.  Google’s servers interpret these packets, as they would any other request sent via the internet,2 and handily fetch the necessary coordinates thanks to their Geocoding API, which “exposes” the relevant data in the computer-language called “JSON.”  These coordinates then get sent back to our content manager in “human-friendly” language like JavaScript and html (thanks again to Google’s Javascript API).

All in all, the process looks like this:

Workflow for how Google's API works

Slide from Le Wagon

This process has saved both your content manager and web developer a lot of time.  This is one of the main advantages of an API.  Not only does it let the end user do some cool stuff, it also saves programmers a lot of effort by allowing them to streamline what would be a lot of tedious coding to reproduce these same processes without the help of the API. As David Berlind says on Programmable Web (an extensive online API directory):

The extent to which APIs make oft-repeated yet complex processes highly re-usable with just a single or few lines of code is fundamental to developer productivity, modern day application development and the API economy.”

And indeed, this “API economy” is in full swing. Now that we know what to look for, you can find APIs practically everywhere: Google, Twitter, YouTube, Facebook…they all provide APIs to their data so programmers can do things like insert maps right onto their website, or help consumers log into a third-party app via Facebook. The possibilities are pretty much endless, and can go from relatively simple to quite complex.

For example, going back to our TimeOut content manager, let’s say we advertised a concert that ended up getting cancelled. They need to send a text message to all the people who bought tickets via their website to let them know.  Their two options are: 1) They can whip out their cellphones and manually send 500 text messages, 2) use an API like CALLR that, when integrated with TimeOut, can send these text messages automatically using the same principles explained above.

snapshot of CALLR's API

A few lines of code lets web developers use CALLR to send automated text messages

We can again see here the advantage of using an API – a drastic increase in efficiency, and the ability to create complex workflows that can enrich a business’s value proposition.

Want to add SMS to your apps and services?

Check out our API

Webhooks and the Hollywood Principle

Something we alluded to above that deserves more explanation is the idea that APIs ‘make requests,’ (often referred to as “calling the API”). This inevitably takes up a server’s resources.  Indeed, many commercialized APIs will limit users as to how many requests can be made in a certain timeframe in order not to overload their system.

In some scenarios, it would be much more effective if, instead of having to constantly call an API to see if information has been updated, the API could just send the information as soon as it comes in.

For examples, let’s say you’re a retail website, and you’ve integrated Stripe’s API to help your customers easily buy your merchandise.  As they explain, there are certain important events that will happen on their end that won’t necessarily show up with an API request.  Even if they did, that would mean your server would have to be constantly calling Swipe’s API to see if any of these things had happened – not an efficient use of resources. However, if your retail website isn’t aware of these events – like when a subscription payment fails – this could lead to unhappy customers.

Webhooks help solve these issues by reversing the ‘API request’ workflow. Instead of waiting for a program to make a request to the API, the API can notify the program directly if a pre-assigned event takes place.  As Thomas explained, this is known as the ‘Hollywood principle’ – don’t call us, we’ll call you.  For Stripe, webhooks could be used to update a customer’s membership record when a payment succeeds or fails, log a dispute, etc. At CALLR, we use webhooks for similar scenarios: to let our clients know when a text message has been delivered, when their balance is low, or a host of other scenarios.  Thomas, who organized APIs for Beginners via Meetup, could have used a webhook to ask Meet Up’s API to automatically notify them when a new person RSVPs.

Text explaining how to use web hooks

Slide from Le Wagon

Webhooks in Action

To finish up this article, let’s take one last quick look at how we can put all of these principles together to create an efficient, automated workflow.

Image you’re a sales rep visiting a trade show. You’ve brought your iPad with you to keep track of and log the prospects you chat with. You and your team have been using Wufoo and Trello in your tech stach – Wufoo to collect leads’ contact info, and Trello for lead management with the rest of the sales team.

Text describing lead management system

Slide from Le Wagon

As anyone who has ever prospected at a trade show knows, the process is exhausting. The last thing your sales rep wants to do is manually jot down a lead’s contact info, do a bit of online digging, and compile this aggregated info on a Trello card for each and every person they talk to.  Enter Zapier (that we mentioned earlier), a very trendy web app that does the job of connecting different APIs for smarter workflows (without you needing to know how to code).

Our salesperson could use Zapier to do a few things: first, using a webhook, they could ‘ask’ Wufoo to interact with Trello, creating a new lead card as soon as a new Wufoo form is filled out.

Zapier API example

This already cuts down on some time for our sales rep.  But we can even go a step further using a service called ClearBit.com. ClearBit uses any email address you enter to pull up relevant information on the web associated with that address (you can try it yourselves on their site).

Example of how ClearBit works

If we use Zapier to integrate them into our workflow, our sales rep can automatically add this complementary information as soon as a new card is created.  And voila!  Now, each time our sales rep enters a prospect’s email address on Wufoo, a pre-populated card automatically gets created on Trello (for the whole sales team to see), with any notes from the Wufoo form and additional information provided by ClearBit – with no extra sweat from our sales guy.

And there you have it: a super easy way to make use of APIs to streamline your workflow – without using a single line of code.

Key takeaways

If you still have any lingering questions about APIs or coding in general, you can always check out Le Wagon on MeetupInstagramFacebook and Twitter, or even take a sneak peek at CALLR’s API documentation.

Some things to remember:

  • An API is an Interface used by Programs to interact with an Application
  • APIs expose data
  • Developers write programs which consume APIs
  • Google, Facebook, Uber, CALLR, and Trello are all good API examples … almost every tech-oriented service provides useful APIs
  • Developers plug them to their applications and don’t have to reinvent the wheel
  • This lets them focus on their applications’ core business / value
  • APIs are designed to expose data in a machine-readable format (often JSON)
  • Whereas websites are designed to expose (often the same) data in a human-readable format (images, links, forms…)
  • Webhooks are reversed API calls: the HTTP request is sent by the external service and received by your application

P.S. This article was focused mostly on web APIs, but there are many other API types out there

  • [1] (Applications could be a web application, software, database, machine…)
  • [2] As Thomas explained, the internet is, in fact, just a continuous series of requests and responses shouted from one server to another in “computer-speak”