What is an API? A helpful analogy and a few examples

Let's face it: Some of us developers have no clue how to really answer the question, What is an API?

We code day in and day out and since we never have to deal with any API, we put it on that list of things we'll figure out later.

And it's okay to figure it out later. Maybe your job or daily "thing" doesn't involve APIs at all.

Regardless, I want to take a minute to give you an analogy I read recently to help you out if you ever have to explain it to someone else, and even if you just need a way of understanding the concept better.

What is an API? The Analogy

I read this in a book called "Learning WordPess REST API" by PACKT Publishing. And I'll quote here:

In simple words, an application programming interface lets you establish a connection or link between two different types of software. For instance, your computer has a USB port, which is essentially meant for connecting USB storage devices such as flash drives or USB hard disks. However, you can connect virtually any type of USB hardware to the portprinters, smartphones, tablets, and so on. As such, think of the USB port as an API for letting you connect different types of devices to your computer and allowing your computer to interact with the concerned devices accordingly. Much like a USB port facilitates the exchange of data between two physical devices, an API facilitates the exchange of data between two different types of software.

– Learning WordPress REST API by Sufyan bin Uzayr

So with our USB ports, we plug up USB drives, printers, phone chargers, cameras, etc. and they all, despite being different, can "talk" to our computer via the USB port. In this way, the USB port is much like an API.

So, What is an API? Use and reference this USB port analogy.

Common uses of APIs

We use APIs daily. When we are registering on a site and it allows us to login via Facebook or Google. API! Think about the apps you use…do any of these have Integrations (with Google calendar, Stripe, etc.) API!

GitHub API

Do you have a Github account? If so, type https://api.github.com/users/yourusername
in the browser (replacing yourusername with your actual username). You will receive some JavaScript Object Notation (JSON) data about your account. If you were building an app that needed to access Github data, you could make a request for it this way. Add in some authentication and you could send data and even update data in your account (or any user that uses your app could do for their own account).

**Side note: JSON is great because it is both machine readable AND human readable. Also, many popular programming languages offer their own interpreters to parse the JSON making it great for cross platform interaction.

WordPress API

Another example: The WordPress REST API. If I wanted to GET the posts from my own website I can simply make a request to https://travis.media/wp-json/wp/v2/posts. Try it with your site, just change the domain name. (Look like gibberish? Download the JSON Formatter Chrome extension to see it parsed.)

YNAB API

In a final example, YNAB (the best budgeting app of them all) recently opened up its API.

Let's say I wanted to create an app that gives the user a visual dashboard of their finances with dials and buttons, etc. that was more appealing than the YNAB interface.

I could talk to the YNAB API and make GET requests to pull data, POST requests to send data, PUT to update data, and DELETE to delete data.

So I could pull data and show it with some sort of dials. I could list the unapproved transactions and approve them from my applications. I could add new categories, delete new categories, etc., etc. You get the point.

Conclusion

That's as far as I want to go with it in this post. Hopefully, this analogy will help you out when explaining, What is an API?, to others and even perhaps helping with getting a clearer understanding in your own head about it. Thanks for reading.