How Software Talks to Other Software Just Like Humans Do: APIs Explained

"Why does everyone keep saying APIs are important?" you say. "I thought I knew what they were, but now I'm not so sure."

You're not alone! Most people aren't technical; but some make themselves seem technical by saying things like "APIs" and "protocol". But you can learn this too, and once you do, it's like knowing the language of magic.

Spoiler: At the bottom, I'll show how to use APIs without any code to do this very magic.

Don't be scared. Here's what APIs are.

An API is the way modern software tools communicate with each other, letting them work together just like we work together as humans.

Let's consider the way we work as humans as a metaphor. There are two ways we communicate with each other: when we realize we NEED things and when something happens and we have to INFORM someone. Others too, because we're not machines (well, most of us are not) and like to have jokey banter and occasionally airdrop memes to each other, but these are the transactional ways.

  • Need: "I am hiring some more staff next. How do I get them set up with laptops and company t-shirts and drink bottles? "You ask some people to do it, and they help you out..‌‌
  • Inform: Your boss asks you: "Every time you do an expense report, can you email (inform) me, so I don't miss it?" Sure thing, you say.

APIs automate those 'need' and 'inform' situations. ‌‌‌‌There are two main kinds of APIs we use: REST APIs (aka RESTful ones, or 'endpoints'), which wait around until you need something, and 'triggers' (also known as 'webhooks'), which inform proactively.‌‌

Example of a REST ('need') API: These are APIs that are waiting around to be asked something (RESTing, I think).

You go to Google Maps and click on 'Home'. The app queries a series of APIs (who were waiting around to be asked... RESTing, I think) to find out

  • From Google Maps: All the routing information and traffic times
  • From Lyft/Uber: An estimate of the prices to get a ride
  • From Yelp: Some well reviewed places to eat near home that are open

Example of a Trigger ('inform') API: These all involve a listener, which is sitting around waiting for it to be told something.

You pay for your coffee at some cafe using Square. Square says 'yo this person just dropped $6 on a cappuccino' to some survey software via a trigger. The survey software sends you an email asking you if it was worth listening to the barista's edgy vinyl for 15 minutes after taking your money while he slowly worked through the queue.

‌‌Why APIs are important‌‌

A well-written API is important for two reasons.‌‌

  1. APIs make it easier to connect applications, saving time and money of developer costs. If we have to integrate software (like, for example, payroll, HR and procurement software), we want to make sure the developers planned on their software being easy to connect with other people's software. This includes them thinking about security standards. There's LOTS of ways of providing a secure API and authenticating, and this is super critical to a huge company. (If a company that holds your SSN has an API, you want to be really sure they're not going to get hacked.)‌‌
  2. Having a good API implies that the company is really structured and organized. A good API with good documentation is like meeting someone with really good filing and organization. It makes them seem trustworthy and un-chaotic. (Note to self: tidy desk before sending this email)

‌‌What APIs look like when they communicate‌‌

You only need to know it looks like this and that it's intelligible; you don't need to understand it or how to write it. There are ids in there, plus text and other stuff.

{
	"event_id": "12345",
	"event_type": "form_response",
	"response":
		{
			"form_id": "lT4Z3j",
			"submitted_at": "2018-01-18T18:17:02Z",
			"definition": {
				"title": "Webhooks example",
				"fields": [
					{
						"id": "DlXFaesGBpoF",
						"title": "Thanks, Dana! What's it like where you live? Tell us in a few sentences.",
						"type": "long_text"
					},
					{
						"id": "SMEUb7VJz92Q",
						"title": "If you're OK with our city management following up if they have further questions, please give us your email address.",
						"type": "email"
					},
					{...

The best part: How to use them to perform magic WITHOUT CODE‌‌

There are three main ways: what engineers do (expensive; wait until two quarters from now), existing connections (very limited, like Typeform automatically connects to Google Sheets), or cool things like Zapier and IFTTT.‌‌ I'll focus on Zapier, though IFTTT and other apps do similar things.

Zapier is a piece of software that takes inputs, processes them and produces outputs.

Kind of like this.

Here are some examples of how I have used them at work and personally

  • Every time I create a new blog post, make a marketing post and put it on Twitter, Facebook, LinkedIn and email it to every subscriber. (This saves me about 15 minutes each time it runs)
  • Every time a visitor checks into a center, create a ticket for them in a queueing system, and send them an SMS afterwards with a follow-up survey. (This saved about 3 minutes per interaction, which for us, added up to 5,000 hours a month).
  • Every day at 8am, send me a picture of a motorcycle with a countdown timer to my last day at work saying how many days were remaining.

I'll write a follow-up post about some of the cooler things you can do via Zapier.

PS What does API stand for?

You'll notice I didn't even explain what it stands for. It almost doesn't matter, because it doesn't help explain it. Application Programming Interface. You happy? Did that help? You're welcome.