Intro to using APIs
21 May 2019
Previously, I explained than an “application programming interface,” or API, is a set of protocols for communicating with a computer as if you were knocking on the door of a fortified castle.
This series will do a beginner-level deep dive into how you go about knocking on these castle doors.
This skill often enables you to communicate with your favorite cloud services in new ways or to automate the ways in which you already interact with them.
Scope: other people’s HTTPs APIs
This is not a guide to “carving a door into your own fortress” and providing an “API” to other people that would allow them to ask your computer for favors.
The internet contains many fabulous tutorials about setting up a “web server” and turning it into an “API endpoint,” but this isn’t one of them.
This is merely a guide to using the “APIs” that other people have provided.
Furthermore, this only covers APIs that communicate over the internet using the “HyperText Transfer Protocol” (HTTP(s)), which is the most common everyday use of the word “API” today.
Preparation
Read about HTTP(s)
I can’t strongly enough recommend reading some theoretical explanations of the HyperText Transfer Protocol (HTTP).
A protocol is simple: it’s a set of rules for interacting with someone else.
In my introduction to APIs, I said that if we were talking about a real-world protocol for communicating with people inside a fortified castle, the communications protocol might look like this:
“If you have something for the fortress, bring it in a series of pink 12x12x12 boxes. Paint the first one with green stripes and the last one with purple polka dots. Put your name and return address on all of them.
“If we like them, we’ll figure out what to do with the stuff inside the boxes from there.
“After we’re done, we’ll post a receipt on the door telling you whether we handled your boxes neatly or burned them.”
The protocol for HTTP(s) is, obviously, a bit more technical. Something more like this:
“If you want to talk to the fortress, send us a Transmission Control Protocol (TCP)-formatted series of 0’s and 1’s representing appropriate words like ‘GET’ or ‘POST’ and a return address for your castle.
“Send your message to our fortress door #80.
“We’ll send a TCP-formatted series of 0’s and 1’s representing appropriate words like ‘STATUS’ to your return address, letting you know what we thought of your attempt to communicate with us.”
Obviously I’m still hiding a lot of detail.
That’s largely because you can trust your “messenger” (software or a programming language) to take care of the “0’s and 1’s” and the “TCP” formatting.
You can even trust your software or your programming language to take care of ensuring that your messages are properly formatted according to the HTTP(s) protocol … if you look up its documentation on what buttons you’re supposed to be clicking or what commands you’re supposed to be using.
That “if” is why it’s useful to study, at a conceptual level, what a good HTTP(s) request looks like.
Analogy: It’s relatively easy, as an adult, to decide to prepare for a trip to Mexico by consulting a bilingual dictionary and memorizing 50 Spanish words for concepts like “toilet,” “flight,” “breakfast,” etc. Yet you probably wouldn’t bother to give your young toddler the same task, even if they’re coming with you.
- Q: Why?
- A: Because as an adult, you’ve already mastered concepts like languages and toilets and air travel and meals.
Similarly, you’re going to find it a little easier to read the instructions for your software or programming language of choice once you have a basic understanding of concepts like these:
- The HTTP(s) protocol consists of you sending “requests” and receiving “responses”
- Your requests should be categorized as “GET,” “POST,” “PUT,” etc.
- Your requests may have a “header” and a “body”
- What kinds of information about your request you might be expected to put in its header or body
- The responses you get back should have a “status” and may also have a “header” and a “body
Furthermore, every HTTP(s)-based “API” you meet will have arbitrary rules along the lines of “pink 12x12x12 boxes, the first one painted with green stripes and the last one painted with purple polka dots.”
It’s nice to have “understanding basic HTTP(s) request and response rules” out of the way so that you can focus your attention on the API’s arbitrary rules.
Note: in reality, the “pink 12x12x12 boxes” rules will look more like this:
“Whenever we send you an HTTP(s) response to your request for data, please inspect its body for the word ‘more.’
“If you see it, we didn’t send you everything you asked for.
“Please make another HTTP(s) request, putting a note into the body that indicates where we left off.
“Repeat as necessary until you stop seeing the word ‘more.’”
The programming The trick you’ll be learning in your programming language of choice is how exactly to make i
The “representing appropriate words like ‘GET’ or ‘POST’” bit is what we’ll practice in this series … but reading up on the subject ahead of time would definitely help you follow along.
Codecademy’s article is a nice introduction to HTTP(s) requests.
Why “(s)?”
You might note that I keep calling the HyperText Transfer Protocol “HTTP(s).”
What’s up with the “s” in parentheses?
Well, as you can see, the HTTP part is an abbreviation for the name of the protocol.
However, I add the “(s)
” to remind you that, whenever possible, if an API “endpoint” has an address that starts with “http://
,” you should try changing it to “https://
”.
If it doesn’t work with the extra “s” on the end, you shouldn’t send it any “login credentials” or “authentication keys” and also shouldn’t send it any confidential data, because everyone on the entire internet can read and even modify everything you send to, or receive from, that API endpoint (it’s like communicating by postcard).
Read about APIs
Initially, I wrote my explanation of APIs to differentiate concepts like “hosting an API endpoint” vs. “using someone else’s API endpoint” to Salesforce database administrators responsible for planning data integrations.
However, I was careful to write it so that it didn’t rely upon familiarity with Salesforce, so I recommend reading it before you launch into this series.
It’s not very long, and I’m going to keep referring to API endpoints as “castles” and “fortresses” like I do in that post, so it’s a good scene-setter.
This series is a “how-to” tutorial about the 3rd approach described in that article: knocking on the “castle doors” of other people.
Read about XML & JSON
XML and JSON are, essentially, punctuation standards for formatting plain text that help add structure and meaning to the data within that text.
XML involves a lot of <
and >
symbols; JSON involves a lot of [
, ]
, {
, and }
symbols.
If you’re the kind of person who can read something that repeats itself and “follow along” without too much trouble, you might not need to know more than that.
But if you’d like more context, I wrote a 7-part “zero to comfortable” beginner’s tutorial called “Intro to XML and JSON.”
Takeaways & What’s Next
That’s it for today – just some “recommended reading” before we start with hands-on exercises!
The main things to remember about what you’ll learn in this series are:
- Talking to another system’s “API” is kind of like knocking on a fortified castle door and talking through the guard’s little eye slot.
- Because we’re talking about computer-to-computer communication, everything is done within computer-friendly standards like HTTP(s), XML, & JSON.
- It’s handy to have a “beginner-intermediate” grasp of them so that you can focus on the additional rules presented by the particular API you’re trying to communicate with.
- Security matters. Don’t be careless with passwords and sensitive data. Someone’s always waiting for you to make one false move.
- You don’t have to learn to code to take advantage of HTTP(s) APIs – there’s downloadable software such as Postman that lets you point-and-click your way through writing great HTTP(s) requests.
- This is worth doing for its own sake, even if you don’t have time to learn to code!
- Many enterprise-level “Extract, Transform, Load” (ETL) tools have a rather point-and-click user interface along the lines of Postman, so you really can learn a useful skill without learning to code.
- However, if you are learning to code, or know how to code, you’ll want to learn to leverage HTTP(s) APIs in your programming language of choice.
- To really leverage APIs, you might need to level up your programming skills with respect to “data structures” and “file I/O.”
- (That is, if the API’s rule is “use pink 12x12x12 boxes,” you need to know how to cut a box to size and how to color it pink.)