Hey guys, welcome to another lesson on APIs.
In this lesson, we're going to be talking about how to format your API requests, and by the end of
the lesson you will understand what are Endpoints, what are Path Parameters, what are Query Parameters
and how you can format and change your API requests.
What we've seen so far is we've built frontends for our websites and we've built backends for our
websites and they can interact with each other through requests and responses.
Our front-end might make a GET request to our back-end and in return, for example, you want to open
a different web page.
So then you would make a GET request and your server would send back some response with some code,
with some data.
Maybe that can go into your EJS file and be displayed to the user.
This, if you think about it, is effectively hitting up a private API.
Now the reason why it's private is because you don't document it for other people to use.
Your server is exclusively serving your own front-end and not somebody else.
However, if somebody else knew how your server was structured and tried to hit it up, that would be
tapping into a private API, and people do in fact do this
if there is some sort of strong reason to do that.
Now, normally, however, what you're interested in doing is getting your server to talk to somebody
else's server and get some data or do something and interact with that server in some sort of way.
And this is again done using requests and responses, but this time it's done via a public API and it's
public because this particular server has allowed this kind of behavior.
So they've probably documented how to use their public API,
they've exposed certain parts of their server to anybody who wants to request it,
and that is what we're learning all about in this module, "How to use public APIs."
Now we've created an API for you, which is called the bored-api, and it contains activities that you
can do when you're bored and it's got a whole bunch of data on what you could do, how many participants
it requires, if it's free or if it costs something.
But you can take a look at the documentation by going to bored-api.appbrewery.com.
And once you head over to the homepage of this API, you will see some documentation and it shows you
all the things that you can do with this public API.
The first thing I want to introduce you to when it comes to structuring your requests to these APIs,
is something called the API endpoint.
Normally, you will have a base URL, something something.com, and then you will have a forward slash (/)
and an endpoint.
This endpoint can be different for different purposes.
For example, in our bored API, there is a forward /random endpoint where you can get hold of random
activities when you're bored.
There is a /filter endpoint when you want to filter the activities based on some sort of
criteria.
And the endpoint is basically a different route on the API provider server and in the documentation
they will usually give you an example of which endpoints you can use and what is the purpose of that
endpoint.
Let's go ahead and try an exercise on Postman.
I want you to hit up the random endpoint on the bored API and I want you to try and get hold of a random
activity each time you make that GET request.
Pause the video.
Take a look at the documentation for the board API and see if you can get hold of a random activity
through Postman.
All right.
So the first place to start with any API is reading through the documentation.
We know that we're trying to get hold of a random activity and the documentation tells us this is what
an example request would look like.
It would be the full path of the API,
and then there is the endpoint.
It's /random. And it even tells us what we can expect to get back when we make that request.
Let's open up Postman and create a new HTTP request.
Now we want to make a GET request to match up with the method in the documentation,
but also we know we're trying to get hold of a resource.
Let's go ahead and copy the URL.
This is the base URL and this is the endpoint and that's pretty much all we have to do in order to hit
it up.
Let's hit Send and send our request to the bored API.
All right.
So it tells us to, "watch a Khan Academy lecture on a subject of your choosing".
This is an education type of activity, only requires one person,
it's totally free to do,
and there's even a link that's provided.
So that's pretty cool.
And you can keep sending requests to this API.
But notice that with most public APIs that don't require authentication, there's usually some method
to prevent people from abusing the resource.
So in our case, we've added a rate limit so that you can only make 100 requests every 15 minutes,
and after you've used up those requests, you'll have to wait for 15 minutes.
So while you're testing the API, 100 should be more than enough to complete all the activities in this
lesson,
but just be aware of that,
and if you see a response where it says you've made too many requests, you'll know what's happened
and you'll know that you just have to wait a little bit.
The next aspect of structuring a request is something called Query Parameters.
We've already seen the endpoint comes at the end of the base URL.
So this is the base URL, this is the endpoint
and then afterwards we can add a little question mark (?) to say that we are adding a query now to the end
of this request.
You start off all the queries with a question mark and then it's basically just a key/value pair, where
this is the name of the query and then you have an equal sign and then you provide the value for that
query.
And it's basically a way to put a key/value pair into the URL when you want to provide some additional
information or some parameters to a request.
Normally when you're hitting up an API, they're used for filtering, sorting, searching, and you
can even have multiple query parameters by simply adding an ampersand (&) after the first query.
So remember, very important thing is in order to begin your first query, you need a question mark
and then you have your key: value pair,
and then after the first pair, if you want to add more queries, you tag them on starting with an ampersand.
So for example, this is query Number 1, query and value. Query Number 2, query and value.
If I wanted to add a third one, I would add another ampersand and then add my query 3 and then
its value.
And these all just get tagged on to the end of the URL.
So let's try doing that in Postman.
If you take a look at the bored API and you scroll down, there's a way for us to be able to filter
activities based on the type of the activity or the number of participants.
And as you can see, it describes to you that these are two optional parameters that we can provide
to filter our activities by. There is a choice of these seven different types of activities.
So you can pass these as values to this query, and you can also choose how many participants you want
to include in your activity.
Forward slash filter is the end point, and it even gives you an example of how you might structure
this request. As a challenge,
I want you to hit up this endpoint to filter activities, and I want you to filter through the activities
to find all of the activities that are social for two people.
Pause the video, open up Postman, and see if you can complete this challenge.
All right, let's open up a new tab and let's put in firstly the base URL and then we can add in our
endpoint, which is /filter.
Notice how Postman has a really handy section where you can actually add in your query parameters by
key and value, and they will format your URL for you.
If we do the first one, which is the type of activity and we want to set it to social, you can see
as I type my key value pairs, it's already formatting my URL for me.
Now, however, if you're writing your back-end code or if you have to write this yourself, you don't
get this neat little feature.
So we should practice how we can structure the URL by ourselves.
As I mentioned before, the first query comes after the question mark and every subsequent query has
to come after an ampersand (&) or the "and" symbol.
Now the next one we want to do is called "participants".
Notice the S, and as always, you have to study the documentation in order to know how to use the API.
So this in our case is plural.
So, participants=2.
And now we've got our two queries both set up even though they're both optional,
but once we go ahead and hit Send, hopefully, we'll get back all the activities that are both social
and set up for two people.
The very last structure that I want you to be familiar with is something called Path Parameters.
So after the base URL, normally comes the endpoint, but an endpoint is usually a fixed path, so it'll
be /random and that endpoint is never going to change.
It's always going to be, /random, spelled in this way.
But we can also have something called Path Parameters where after a forward slash we can add some sort
of parameter that does change, and this is usually to find some specific resource that exists.
So it could be an ID, it could be a username,
it's basically something that's very specific that can identify a resource in the API. Unlike query
parameters, where it could be multiple things like, participants,
well, there were lots of activities with different types of participants or we had the type.
And so I want you to think about query parameters as more for filtering and searching and path parameters,
more for identifying a resource by some specific parameter.
And we can test this out in our last exercise.
So notice that when we look at all the activities that we get back, they all have a unique key and
there's usually some sort of ID or key for each resource where identifies it uniquely.
So there is no other activity with this key or with this ID, and we can use the path parameter, the
key, in order to retrieve a specific activity.
Now, for example, if on your website you know that you want to always display to the user the first
activity as, "Learn Express.js", then you can simply retrieve it by identifying its specific key.
For example, I already know the key for hosting a movie marathon and it's 5914292.
Let's provide this key as a path parameter to query for this specific activity.
So let's open up a new tab and let's structure our request.
So first part is the base URL.
Next comes the endpoint, which in this case is /activity.
So that's the route we're going to hit up using our GET request.
And then afterwards, after a forward slash, we can specify our unique path parameter.
So that's going to go straight into the URL,
and it was that number that I told you.
So now when I hit send, it's going to look through the database of activities and try to match this
key to a specific resource.
And once it's found it, it pulls up the entire activity and sends it back to us.
And so now we've identified this activity,
we've used a GET request to get hold of it, and we use the path parameter to do this.
So those are some of the different ways that we can structure our API requests.
We've learned about endpoints, we've learned about query parameters, and we've also learned about
path parameters.
In the next lesson, we're going to learn a little bit more about the structure of the data that comes
back from an API request.
And when it comes to Web APIs, the format is usually a JSON, so we're going to learn all about that,
what it is and how to use it in our code.
So for all of that and more, I'll see you there.