Intro to using APIs #2: Hands-On No-Code
21 May 2019
Table of Contents
- Download and install Postman
- Tour of Postman
- Step 1: Write your first request
- Step 2: Understand your first response
- Step MAGIC: Celebrate
- Step 3: Add parameters to a request
- Step 4: Add bad parameters to a request
- Step 5: Play with the formatting of a response body
- Step 6: Ask the API to format the response body differently
- Step 7: Try a different HTTP “verb”/”method”
- Step 8: Try editing the Request Header
- Step 9: Try editing the Request Body
- Step 10: Have fun with cat pictures
- Takeaways
- Useful Links
[[[TO DO: Break this post up into 1 post per exercise, with “tour of Postman” as its own standalone post. But add very small “with code in Salesforce” & “with code in Python” setup & execution-result screenshot sections to the end of each.]]]
Hopefully you took a moment to read about HTTP(s) requests, but there’s no way to cement your understanding of a new concept like like trying it.
Let’s dive in – no coding required.
This post looks long, but it’s largely screenshots and descriptions of what’s in them. That way, if you don’t have hands-on time immediately, you can still follow along on a 25-minute bus ride.
- The exercises are fast – less than 1 minute apiece to actually set up and execute
- Hopefully each exercise’s explanation will take just a few minutes to read and digest
Download and install Postman
We’ll do today’s exercises in a wonderful point-and-click tool called Postman – please download, install, and run it on your computer.
Tour of Postman
- Close out the Postman splash screen.
- Click the small white tab with a plus sign (
+
) near the top left part of the screen or navigate toFile
->New Tab
. - By default, Postman will open a new “GET”-typed request editor named “Untitled Request.”
Let’s take a tour of the key parts of Postman’s user interface that you might edit when making a request (official documentation is here).
- Near the top, at left, is a drop-down with options for your HTTP “verb”/”method” like
GET
,POST
,PUT
, and so on. For now, we’ll mostly leave it onGET
. - Next to GET is a place to put the URL, or address starting with
https://...
, of an API “endpoint.” - The big blue button to the right of the URL bar is the “Send” button, which you’ll click when you’ve built a request and are ready to see what it does.
- Below these 3 areas are a bunch of options you can add to your request before you send it. Only some of them are ones we’re particularly interested in at the level of an introduction.
- The first one is “Params.”
Have you ever looked at the URL of a web page you were visiting and seen that it ends with a question mark, followed by a bunch ofsomeKey=someValue
items, separated by ampersands (&
)?
The area that clicking the “Params” tab exposes gives you nice editor where you can type all of these “parameter pairs” in a way that is easy to edit. - The second one is “Headers.”
This tab provides another “list of key-value pairs” editor. These are a little different from the “parameter” pairs in that you don’t see them right in the URL you’re talking to. - The third one is “Body.”
HTTP(s) request bodies are a bit of a free-form area where text structured in a lot of different ways can go (whether the computer you’re talking to understands what you type there is a different question…). Because of this, the “Body” tab has a list of radio buttons offering you different types of editor to compose the body’s contents.
We’ll practice using all of these in the exercises that follow.
Step 1: Write your first request
For our first request, let’s make a very simple one.
- Leave the request as
GET
. - Type
https://yesno.wtf/api
into the URL box. - Click Send.
Step 2: Understand your first response
The section of the screen saying “Hit the Send button to get a response” disappears and is replaced by details about the HTTP(s) response that the web server hosting https://yesno.wtf/api
sends back to us.
There isn’t any hint that the bottom part of the screen is showing us the contents of the “response” – it’s just sort of something you’re supposed to remember about Postman.
Let’s take a look.
Request headers
Before we get into the response, look immediately under the URL box.
The “Headers” tab now has a “(7)” on it, indicating that there are now 7 details in the “headers” section of the request we made.
- Q: Do you remember manually adding any headers to the request? I don’t. What’s going on here?
- A: Postman added some header details that a typical API endpoint might like to see for us. Most tools that help you make HTTP(s) requests will do that to some extent.
Response body
For starters, Postman is showing us the contents of the “body” of the response that YesNo sent back to us.
Postman has guessed that the contents of the response body are formatted according to the JSON standard (we’ll find out how it guessed in a moment), so it made it “pretty” by inserting line breaks and indentations so that it’s easier to read.
As promised by YesNo’s (extremely concise) documentation, we received 3 useful pieces of information in this JSON-encoded text:
- A yes/no/maybe answer
- An indication that we did not force the answer’s value
- The URL to a GIF of Kanye West shaking his head “no”
{"answer":"no","forced":false,"image":"https://yesno.wtf/assets/no/27-8befe9bcaeb66f865dd3ecdcf8821f51.gif"}
Of course, that’s all wrapped up in a jumble of {
,}
,:
, etc. so it doesn’t hurt to know how to read JSON if we’re dealing with more data, or to know how to weed through it all with code if we’re dealing with a lot more data.
Response status / time / size
Further to the right, we can see “Status,” “Time,” and “Size” tidbits telling us whether the HTTP(s) response self-describes as having succeeded or failed, how long it took to get a response, and how big the series of 0’s and 1’s making up the “response” actually is, in Bytes.
Response headers
We can also see that the response came back with 16 details in its “headers.”
The “Headers” tab is grayed out, indicating we’d have to click on it to see the details.
Let’s do that. We’ll also click the “Headers” tab up top and look at what Postman inserted for us into the request we sent.
Up above, in the details for the “request headers,” we can see that the main “Headers” section still says there aren’t any, which is what we thought we were doing.
However, Postman added an area called “Temporary Headers” to make our HTTP(s) request “friendlier.” For example, it identifies itself as Postman. Nothing too interesting to see here.
Down below, in the details for the “response headers,” we can see the “response” self-identifying with a success status of “200”.
We can also see how Postman knew that the response body was formatted according to the JSON standard: the Content-Type
header indicates “application/json; charset=utf-8
.”
Step MAGIC: Celebrate
Pat yourself on the back: you’re now an API programmer!
Okay, you’re a beginner one, but you did it.
Let’s get started with the next exercise.
Step 3: Add parameters to a request
- At top, just below the URL, click the “Params” tab and, in the first available line, under “Key,” type “
force
” and under “Value,” type “maybe
”.- Note: your screen may still be cluttered with the “response” from your previous request. Ignore it. It’ll be replaced by the response to the request you’re building as soon as you click “Send.”
- Note that Postman automatically changes the URL by adding a
?force=maybe
to the end of it. That’s kind of handy…- (Don’t like a key-value pair you added? Hover your cursor in the “Description” area for the key-value pair you’d like to delete. An “
X
” will appear at the far right that you can click to delete the row.)
- (Don’t like a key-value pair you added? Hover your cursor in the “Description” area for the key-value pair you’d like to delete. An “
- Click the Send button.
Take a look at the response.
This time, the JSON-formatted HTTP(s) response body contains:
- An answer of “maybe”
- An indication that we forced the answer to be “maybe”
- The URL to a GIF of “Scrubs” character Dr. Cox shaking his head “undecidedly”
{"answer":"maybe","forced":true,"image":"https://yesno.wtf/assets/maybe/0-16d0d74bfa3eb41e4d583375a475544d.gif"}
Looking at the “request” and “response” headers again, we can see that the “temporary headers” Postman added are pretty much the same.
I happened to notice while clicking “Send” that the “(7)
” disappeared and reappeared, and that the Postman-Token
header slightly changes from request to request, so it seems Postman auto-regenerates these every request.
YesNo still sent us 16 headers with the latest response … nothing interesting has changed.
Step 4: Add bad parameters to a request
Let’s get started with the next exercise.
- Under the “Params” tab of the request builder, change “
maybe
” to “obviously
.” - Click the Send button.
Take a look at the response.
This time, the JSON-formatted HTTP(s) response body contains:
- A yes/no/maybe answer
- An indication that we did not force the answer’s value
- The URL to a GIF of Kanye West shaking his head “no”
The “status” is still “200 OK
.”
In other words, adding a parameter pair of force
and obviously
worked exactly like not adding the parameter at all.
THIS IS NOT ALWAYS THE CASE. It’s simply how things worked with YesNo’s API.
Try it again to confirm:
- Under the “Params” tab of the request builder, change “
force
” to “abcca
” and “obviously
” to “xyzzy
.” - Click the Send button.
Take a look at the response.
Again, everything is as if we hadn’t added any parameters at all.
YesNo’s API designers chose to ignore unexpected parameters, rather than to respond with an error.
Security and Permission
Pat yourself on the back – you’re also now a penetration tester.
(If you ever decide to provide your own API to the internet, know that hackers will try giving random commands to your API to see if you have any security vulnerabilities in response.)
In all seriousness, in extreme circumstances, there can be ramifications to “testing” the doors of other people’s fortresses in ways that they didn’t expect you to knock on them.
Don’t go making random “what-if” tests against APIs that would care.
- Q: Not sure if they’d care?
- A: Ask.
(In this case, I’m presuming this test is safe to do, seeing as YesNo put their API out on the internet specifically to help strangers test making HTTP(s) requests. But perhaps I should ask – it looks like one of the developers is still active on Twitter.)
Step 5: Play with the formatting of a response body
- Change the request URL to
http://www.recipepuppy.com/api
- (Yes, that’s without an “s” – they don’t offer secure interactions – we’ll just have to let the world see us talking to RecipePuppy, postcard-style.)
- Get rid of all parameters, if they didn’t automatically disappear when you changed the URL.
- Click Send.
That’s strange … our response body is full of punctuation that makes it look like it’s probably formatted according to the JSON standard, but it’s all “ugly.”
Let’s try manually clicking the “Auto” drop-down between the response tabs and the response body and changing it to “JSON.”
Phew! That’s better.
We can see that the JSON-formatted HTTP(s) response body contains:
- A reminder that we’re using the Recipe Puppy API
- A version number for the API
- A list of 10 recipes
{"title":"Recipe Puppy","version":0.1,"href":"http:\/\/www.recipepuppy.com\/","results":[{some recipe here},{some recipe here},{some recipe here}]}
- Q: Why wasn’t Postman able to automatically detect that it should do “pretty JSON” when showing us our response body?
- A: Let’s look at the response headers and find out.
It turns out that the Content-Type
header indicates “text/javascript
” instead of “application/json
.”
That’s not inherently bad – it’s just not “JSON”-ey enough to get Postman to auto-pretty-display things for us.
You’ll find over the course of your career that some APIs include more helpful information in their responses than others.
Before we move on, one thing that’s extremely important to note is that nothing changed about the response body when we toggled Postman’s display settings from “Auto” to “JSON.”
However, some APIs, including Recipe Puppy, have extremely useful options that allow us to force them to return a response body formatted a certain way.
Let’s take a look at that now.
Step 6: Ask the API to format the response body differently
- Change the request URL to
http://www.recipepuppy.com/api/?i=onions,garlic&q=omelet&format=xml
- Note that Postman automatically adds 3 key-value pairs to the “Params” list. (If we need to change the parameters further, we can use the list-style editor or change the URL directly. Useful!)
- Here is Recipe Puppy’s API’s official documentation
- Click Send
Take a look at the response body.
This time, the HTTP(s) response body contains a lot of text that seems to be formatted in XML (the <
and >
symbols everywhere and the word “xml
” at the beginning of the text are good hints) contains:
- A note that we’re using “XML version 1.0” (not to be confused with “Recipe Puppy version 0.1” from earlier)
- A list of 10 omelet recipes that make use of garlic and onions
<?xml version="1.0"?><recipes><recipe>some recipe here</recipe><recipe>some recipe here</recipe><recipe>some recipe here</recipe></recipes>
We can also see that Postman immediately knew to display the response as “pretty” XML.
Let’s look at the response headers to see if Recipe Puppy gave Postman a hint.
Sure enough, we can see that the Content-Type
header indicates “text/xml
,” which seems to be what Postman needed to know.
Step 7: Try a different HTTP “verb”/”method”
[[[TO DO: PUT SCREENSHOT HERE]]]
- Change the request URL to
https://httpbin.org/post
- To the left of the URL box, click the
GET
drop-down and change it toPOST
. - Click Send.
[[[TO DO: PUT SCREENSHOT HERE]]]
The JSON-formatted HTTP(s) response body isn’t very interesting.
It just shows us some details about the HTTP(s) request we made. This is nothing we couldn’t have guessed by exploring our settings in Postman.
But now try this:
- Leave the request URL as
https://httpbin.org/post
- To the left of the URL box, click the
POST
drop-down and change it back toGET
. - Click Send.
[[[TO DO: PUT SCREENSHOT HERE]]]
- Instead of saying
200 OK
, the “Status” of our response is405 METHOD NOT ALLOWED
.- That’s a pretty good hint that we did something that the HTTPBin API didn’t like!
- The response body contains a short snippet of HTML formatting a plain-English note saying, “Method Not Allowed. The method is not allowed for the requested URL.”
Moral of the story: changing the HTTP “verb”/”method” of a request can change the API’s response.
Step 8: Try editing the Request Header
- Change the request URL to
https://httpbin.org/headers
- To the left of the URL box, make sure you’re still on
GET
. - Click the “Headers” tab of your request and, in the main “Headers” editor section, add one with a key of
myKey1
and a value ofmyVal
. Then click the next line and add another pair:myKey2
&myVal2
. - Click Send.
[[[TO DO: PUT SCREENSHOT HERE]]]
We can see that the JSON-formatted HTTP(s) response body tells us the key names and values of all 9 headers we submitted (the two we typed on purpose and the 7 that Postman added behind the scenes).
The HTTPBin API alphabetizes the headers by key, so ours are tucked between Host
and Postman-Token.
It seems the HTTPBin API capitalizes the first letter of every key (that or Postman capitalized it on our behalf when sending the request) – there’s always some little detail that’s surprising when working with computers.
{
"headers": {
...,
"Mykey1": "myVal1",
"Mykey2": "myVal2",
...
}
}
This exercise wasn’t very interesting (no GIFs or recipes) because, in truth, there aren’t a lot of APIs that would do anything interesting by modifying the request header alone.
There are two extremely common reasons to put your own data into an HTTP(s) request header:
- To specify details about what’s inside the request body
- To specify authentication details like passwords or API keys
Unfortunately, we haven’t yet talked very seriously about security, so I didn’t want to start you down the rabbit hole of playing around with authentication details.
Step 9: Try editing the Request Body
- Change the request URL back to
https://yesno.wtf/api
- To the left of the URL box, click the
GET
drop-down and change it toPOST
. - Click Send.
[[[TO DO: PUT SCREENSHOT HERE]]]
Well, darn it.
- Instead of saying
200 OK
, the “Status” of our response is404 Not Found
.- That’s a pretty good hint that we did something that the YesNo API didn’t like!
- It’s almost exactly like when
https://httpbin.org/post
didn’t likeGET
, only HTTPBin’s API designers chose to return a status of “405” and YesNo’s API designers chose to return a status of “404.”
Remember, the API designer gets to specify whatever “pink 12x12x12 boxes” protocols they like.
- The response body contains a bunch of HTML giving us a very lovely plain-English note saying, “The page you were looking for doesn’t exist. You may have mistyped the address or the page may have moved.”
- It’s not necessarily easy to read that among all the HTML, but if you click the “Preview” sub-tab of the response body, Postman will make a little web page out of the HTML for you and display it on your screen.
[[[TO DO: PUT SCREENSHOT HERE]]]
- It’s not necessarily easy to read that among all the HTML, but if you click the “Preview” sub-tab of the response body, Postman will make a little web page out of the HTML for you and display it on your screen.
Let’s try again with an API that actually accepts POST-typed HTTP requests.
- Change the request URL back to
https://reqres.in/api/register
. - Make sure that the request is still a
POST
request. - Click Send.
[[[TO DO: PUT SCREENSHOT HERE]]]
Well, darn it.
- Instead of saying
200 OK
, the “Status” of our response is400 Bad Request
.- Maybe that’s “progress” compared to “Not Found?”
- The response body contains very simple JSON-formatted text explaining that we made an error, telling us, “Missing email or username.”
When all else fails, read the directions.
Let’s go read the ReqRes API’s documentation (click on “POST: Register - successful”).
The documentation is a little cryptic, but from what I’m reading, we should be able to somehow give it key-value pairs indicating an e-mail address and a password and get back a “yup, you registered this user” confirmation message.
More specifically, they seem to indicate that they’d like those key-value pairs formatted according to the JSON standard.
The example they give is:
{
"email": "[email protected]",
"password": "pistol"
}
Unfortunately, they don’t tell me whether that’s supposed to somehow go into the “parameters,” the “header,” the “body,” etc.
So it’s up to me to play with Postman and figure it out by trial and error.
First I tried adding email
and password
URL parameters. That didn’t work. Same 400 Bad Request
error.
I happen to know that after URL parameters, the second-most common place to put custom data into an HTTP request is the body.
So I went over to the “Body” tab and started poking around with the radio buttons to see all the different ways that Postman would help me structure the contents of an HTTP(s) request body.
Wow. There are a lot of options.
I guess I’ll try them all.
- “
none
” didn’t let me enter anything, so that’s no good. - “
form-data
” gave me a key-value list editor, so I tried manually typing an e-mail and password in. No luck. Same400 Bad Request
error. - “
x-www-form-urlencoded
” gave me a key-value list editor, so I tried manually typing an e-mail and password in. It worked!- But wait … the documentation didn’t say to go around typing in e-mail addresses and passwords by hand. It implied that I could just copy-paste some JSON.
- Let’s keep going and see if I can find a place to copy-paste their sample JSON.
- “
raw
” looks promising. It’s a big old text-editor block. DARNIT – same400 Bad Request
error. - BUT WAIT. Choosing “
raw
” added a drop-down list to the right of “binary” that says “Text.” And it has an alternative option that says “JSON (application/json).” What if I try that? … It works!- Looking carefully, I can see that what actually happened was that Postman added new “Header” of
Content-Type
with the value “application/json
” to my request (click the “Headers” tab). - In fact, if I click the “X” that appears by hovering over that header’s “Description” section at the far right, and go back to “Body,” my drop-down has flipped back to “Text.”
- Moral of the story: just like Postman’s display settings handle response bodies better when the response header is clear about what’s inside, some APIs handle request bodies better when the request header is clear about what’s inside.
- Looking carefully, I can see that what actually happened was that Postman added new “Header” of
- “
binary
” didn’t let me enter anything (it had a file picker, but nowhere to type), so that’s no good.
Let’s take a look at the two options that actually worked for me:
[[[TO DO: PUT SCREENSHOT HERE]]]
[[[TO DO: PUT RESPONSE EXPLANATION HERE]]]
[[[TO DO: PUT SCREENSHOT HERE]]]
[[[TO DO: PUT RESPONSE EXPLANATION HERE]]]
Finally, we got it working. Give yourself a high five.
All right, let’s do what every programmer does when they finally get a sample working: try to do real work!
Let’s try someone besides Eve Holt.”
I’m going to change [email protected]
to [email protected]
and resubmit.
[[[TO DO: PUT SCREENSHOT HERE]]]
Well, darn it.
- Instead of saying
200 OK
, the “Status” of our response is400 Bad Request
. - The response body contains very simple JSON-formatted text explaining that we made an error, telling us, “Note: Only defined users succeed registration.”
- Q: What did we learn?
- A: Not everyone publishes very good API documentation!
Guess which blogger spent 20 minutes learning this lesson the hard way before getting ReqRes’s API to work at all?
I wouldn’t say that ReqRes’s documentation is clear about not being able to use your own e-mail address. Their web site could certainly be more explicit.
Moral of the story:
Using APIs doesn’t require coding, thanks to point-and-click tools like Postman.
However, it most definitely does require the same level of patience with trial and error that all games of “talking to a computer” require – especially in the face of inadequate documentation.
Step 10: Have fun with cat pictures
- Visit this massive list of publicly available APIs and choose one that doesn’t require “authentication” (login) – it should say “No” in the “Auth” column.
- Choose one.
- Sometimes, the link from this list will take you to the “API endpoint” that you need to punch into Postman as a URL and the documentation isn’t obvious – if it’s something like
https://testapi.com/theapi
, try visiting plain oldhttps://testapi.com/
and seeing if the documentation lives there.
- Sometimes, the link from this list will take you to the “API endpoint” that you need to punch into Postman as a URL and the documentation isn’t obvious – if it’s something like
- Play around with it in Postman and tell me what you discovered.
Takeaways
- You don’t ever have to learn to program to make use of APIs.
- 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.
- That said, the work you did today definitely has you “thinking like a programmer,” so you’re totally already programming in a “point-and-click” sense.
- Seriously. Do I have to say it again? You just did a lot of heavy lifting.
- Don’t try this with “real” corporate systems until you learn more about security.
- Using HTTPS, and avoiding APIs that don’t have it, is a must.
- Making sure you aren’t just typing a password into something like Postman’s saved settings is also crucial. You can’t just go around leaving passwords, API keys, etc. in plain text on your computer. Securely storing authentication credentials for APIs is a huge standalone topic to master before trying it on important things.
- Mind-blowing fact: When you visit a web site in Firefox or Chrome or Safari, the things you did today are all your web browser is doing.
- Remember the responses that gave us an error message surrounded by HTML?
- A web site is just a URL that, when things go correctly, responds with HTML-formatted text in the body.
- A web browser is just a tool that’s really good at interpreting HTML-formatted text into “stuff on your screen,” a lot like Postman’s body -> preview tab made it easier to see the contents of our
404 Not Found
error message from ReqRes.
Useful Links
- HTTP requests tutorial by Postman
- HTTP methods list by the Mozilla Foundation
- HTTP status codes list by the Mozilla Foundation
- A lot of publicly available APIs – choose one that doesn’t require “authentication” (login).