An intro
Another acronym!
Hooray, I love acronyms!
What does it mean.....?
API stands for 'Application Programming Interface'
Mysterious...
Yes, indeed.
Tech does love to be mysterious. Almost all applications have APIs and they are essentially contracts telling you what you can do with a system and how to get the data you need.
Like a rulebook?
Kinda, but not as specific as that.
In my Newbie Dictionary, API has been defined as:
"Stands for Application Programming Interface, is a software intermediary that allows two applications to talk to each other, is a contract between you and the software that you want to use, telling you what you can and can't do with it. It's a bridge allowing you to use the software and integrate it with your code, so that it becomes easier to integrate. Example- The google maps API allows you to integrate their maps to your apps through their API."
That's a pretty good definition, but what does that actually mean?
Let's take the Google Maps example further; say you wanted to have a map of your business location displaying on your site (this is a common use case).
You'd access your code, specifically your JavaScript, HTML and CSS for the map, and include the following:
HTML:
<!DOCTYPE html>
<html>
<head>
<title>Simple Map</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script src="./index.js"></script>
</head>
<body>
<div id="map"></div>
<!-- Async script executes immediately and must be after any DOM elements used in callback. -->
<script
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=&v=weekly"
async
></script>
</body>
</html>
JavaScript:
let map;
function initMap() {
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
CSS:
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
You could do this right now (assuming you have set up a billing account for google cloud) and have a little page running locally with a map on it.
Cool
In the above example, we have accessed the Google Maps API.
But it all happened so fast!
It did. Let's break it down.
Look back at the HTML block. In the <script> tag at the bottom (that's where JavaScript lives on that page), we have a little src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=&v=weekly" This src is called an endpoint and it is pointing at what looks like a normal URL, and in fact it is, but that is actually a request to the Google Maps API. It's saying 'Hey, I need the weekly maps sent over to me please, look - I am authorised, I have an 'API key!'
The API key gives you access to the API. In Google's case, you probably get it when you set up a billing account and email. It would look something like this:
b07fa21a-8863-4953-8aae-22027540a782
I got this key from a random API key generator on codepen
You'd enter that into where it says YOUR_API_KEY in the src we looked at earlier. Forgetting to do this or copy/pasting it incorrectly is a common mistake and is one of the first things you should check - are all of the characters there or did you chop off one by mistake?
So is an API always a map or something that you add to your site?
Unfortunately for you, and for anyone trying to explain of understand APIs, an API can literally be anything.
A Content management system?
There's an API for that
A scientific calculator?
There's an API for that
Randomly generated dog photos?
There's an API for that (here, you know you want to)
You get the picture. Just know that an API is like a bridge that gives you access (and tells you how to access it) to data. It doesn't always transfer data back to you, but as long as you have a magic key, you have access.
If they all work so differently and do different things, how will I ever know how to use them?!
Documentation my friend, documentation. All APIs will have documentation of some kind, and this will contain steps about how to use it.
If you are still reading down here rather than looking at randomly generated dog images, firstly hello 👋🏻 and secondly, why are you not looking at dog pictures?!
While you're there, take a look at the documentation, there are multiple endpoints that you could use in your project. It's free, too!
If you want to look at more examples of APIs that we use in our everyday life, I recommend this site
This weather API gives you an idea of how different endpoints can give you different things
So you've heard of REST, HTTP, GET, POST, AUTHENTICATION and all this other stuff?
Hold tight, that's a little out of the scope of this article, but I'm collecting resources and knowledge for a Part II and maybe a Part III.
'API' is a big subject, and although I've used them in the past, I've not fully understood what they ** are ** and what the details are.
We are all codeNewbies here...
Top comments (3)
I was surprised to see APIs compared to contracts. Then my surprise led me to attempt to concoct my own analogy: a librarian.
An API is like a super fast, digital librarian. The librarian oversees all of the library's contents (AKA books in this metaphor). When we, the API user, send a GET request, we a asking that API librarian to "get" us a particular book (i.e. piece of info). I think this analogy even works for PUT | POST | DELETE requests, but in those instances you (the user) are acting more like the library owner instead of a library customer, since you are getting to make decisions about the books that the library keeps in stock.
I love this analogy, great job!!!
Happy to lend the assist :)