Hey guys, welcome to another lesson on APIs. 1
In this lesson, we're going to be talking about how to format your API requests, and by the end of 2
the lesson you will understand what are Endpoints, what are Path Parameters, what are Query Parameters 3
and how you can format and change your API requests. 4
What we've seen so far is we've built frontends for our websites and we've built backends for our 5
websites and they can interact with each other through requests and responses. 6
Our front end might make a GET request to our backend and in return, for example, you want to open 7
a different web page. 8
So then you would make a GET request and your server would send back some response with some code, 9
with some data. 10
Maybe that can go into your EJS file and be displayed to the user. 11
This, if you think about it, is effectively hitting up a private API. 12
Now the reason why it's private is because you don't document it for other people to use. 13
Your server is exclusively serving your own frontend and not somebody else. 14
However, if somebody else knew how your server was structured and tried to hit it up, that would be 15
tapping into a private API and people do in fact do this 16
if there is some sort of strong reason to do that. 17
Now, normally, however, what you're interested in doing is getting your server to talk to somebody 18
else's server and get some data or do something and interact with that server in some sort of way. 19
And this is again done using requests and responses, but this time it's done via a public API and it's 20
public because this particular server has allowed this kind of behavior. 21
So they've probably documented how to use their public API, 22
they've exposed certain parts of their server to anybody who wants to request it, 23
and that is what we're learning all about in this module, "How to use public APIs." 24
Now we've created an API for you, which is called the, bored-api, and it contains activities that you 25
can do when you're bored and it's got a whole bunch of data on what you could do, how many participants 26
it requires, if it's free or if it costs something. 27
But you can take a look at the documentation by going to bored-api.appbrewery.com. 28
And once you head over to the homepage of this API, you will see some documentation and it shows you 29
all the things that you can do with this public API. 30
The first thing I want to introduce you to when it comes to structuring your requests to these APIs 31
is something called the API endpoint. 32
Normally you will have a base URL, something something.com, and then you will have a forward slash (/) 33
and an endpoint. 34
This endpoint can be different for different purposes. 35
For example, in our bored API, there is a forward /random endpoint where you can get hold of random 36
activities when you're bored. 37
There is a /filter endpoint when you want to filter the activities based on some sort of 38
criteria. 39
And the endpoint is basically a different route on the API provider server and in the documentation 40
they will usually give you an example of which endpoints you can use and what is the purpose of that 41
endpoint. 42
Let's go ahead and try an exercise on Postman. 43
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 44
activity each time you make that GET request. 45
Pause the video. 46
Take a look at the documentation for the board API and see if you can get hold of a random activity 47
through Postman. 48
All right. 49
So the first place to start with any API is reading through the documentation. 50
We know that we're trying to get hold of a random activity and the documentation tells us this is what 51
an example request would look like. 52
It would be the full path of the API, 53
and then there is the endpoint. 54
It's /random. And it even tells us what we can expect to get back when we make that request. 55
Let's open up Postman and create a new HTTP request. 56
Now we want to make a GET request to match up with the method in the documentation, 57
but also we know we're trying to get hold of a resource. 58
Let's go ahead and copy the URL. 59
This is the base URL and this is the endpoint and that's pretty much all we have to do in order to hit 60
it up. 61
Let's hit Send and send our request to the bored API. 62
All right. 63
So it tells us to, "watch a Khan Academy lecture on a subject of your choosing". 64
This is an education type of activity, only requires one person, 65
it's totally free to do, 66
and there's even a link that's provided. 67
So that's pretty cool. 68
And you can keep sending requests to this API. 69
But notice that with most public APIs that don't require authentication, there's usually some method 70
to prevent people from abusing the resource. 71
So in our case, we've added a rate limit so that you can only make 100 requests every 15 minutes, 72
and after you've used up those requests, you'll have to wait for 15 minutes. 73
So while you're testing the API, 100 should be more than enough to complete all the activities in this 74
lesson, 75
but just be aware of that, 76
and if you see a response where it says you've made too many requests, you'll know what's happened 77
and you'll know that you just have to wait a little bit. 78
The next aspect of structuring a request is something called Query Parameters. 79
We've already seen the endpoint comes at the end of the base URL. 80
So this is the base URL, this is the endpoint 81
and then afterwards we can add a little question mark (?) to say that we are adding a query now to the end 82
of this request. 83
You start off all the queries with a question mark and then it's basically just a key/value pair, where 84
this is the name of the query and then you have an equal sign and then you provide the value for that 85
query. 86
And it's basically a way to put a key/value pair into the URL when you want to provide some additional 87
information or some parameters to a request. 88
Normally when you're hitting up an API, they're used for filtering, sorting, searching, and you 89
can even have multiple query parameters by simply adding an ampersand (&) after the first query. 90
So remember, very important thing is in order to begin your first query, you need a question mark 91
and then you have your key: value pair, 92
and then after the first pair, if you want to add more queries, you tag them on starting with an ampersand. 93
S o for example, this is query Number 1, query and value. Query Number 2, query and value. 94
If I wanted to add a third one, I would add another ampersand and then add my query 3 and then 95
its value. 96
And these all just get tagged on to the end of the URL. 97
So let's try doing that in Postman. 98
If you take a look at the bored API and you scroll down, there's a way for us to be able to filter 99
activities based on the type activity or the number of participants. 100
And as you can see, it describes to you that these are two optional parameters that we can provide 101
to filter our activities by. There is a choice of these seven different types of activities. 102
So you can pass these as values to this query, and you can also choose how many participants you want 103
to include in your activity. 104
Forward slash filter is the end point, and it even gives you an example of how you might structure 105
this request. As a challenge, 106
I want you to hit up this endpoint to filter activities, and I want you to filter through the activities 107
to find all of the activities that are social for two people. 108
Pause the video, open up postman, and see if you can complete this challenge. 109
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 110
endpoint, which is /filter. 111
Notice how Postman has a really handy section where you can actually add in your query parameters by 112
key and value and they will format your URL for you. 113
If we do the first one, which is the type of activity and we want to set it to social, you can see 114
as I type my key value pairs, it's already formatting my URL for me. 115
Now, however, if you're writing your backend code or if you have to write this yourself, you don't 116
get this neat little feature. 117
So we should practice how we can structure the URL by ourselves. 118
As I mentioned before, the first query comes after the question mark and every subsequent query has 119
to come after an ampersand (&) or the "and" symbol. 120
Now the next one we want to do is called "participants". 121
Notice the S, and as always, you have to study the documentation in order to know how to use the API. 122
So this in our case is plural. 123
So, participants=2. 124
And now we've got our two queries both set up even though they're both optional, 125
but once we go ahead and hit Send, hopefully, we'll get back all the activities that are both social 126
and set up for two people. 127
The very last structure that I want you to be familiar with is something called path parameters. 128
So after the base URL normally comes the endpoint, but an endpoint is usually a fixed path, so it'll 129
be /random and that endpoint is never going to change. 130
It's always going to be forward slash random spelled in this way. 131
But we can also have something called Path Parameters where after a forward slash we can add some sort 132
of parameter that does change and this is usually to find some specific resource that exists. 133
So it could be an ID, it could be a username. 134
It's basically something that's very specific that can identify a resource in the API. Unlike query 135
parameters, where it could be multiple things like, participants, 136
well, there were lots of activities with different types of participants or we had the type. 137
And so I want you to think about query parameters as more for filtering and searching and path parameters, 138
more for identifying a resource by some specific parameter. 139
And we can test this out in our last exercise. 140
So notice that when we look at all the activities that we get back, they all have a unique key and 141
there's usually some sort of ID or key for each resource where identifies it uniquely. 142
So there is no other activity with this key or with this ID, and we can use the path parameter, the 143
key in order to retrieve a specific activity. 144
Now, for example, if on your website you know that you want to always display to the user the first 145
activity as learn ExpressJS, then you can simply retrieve it by identifying its specific key. 146
For example, I already know the key for hosting a movie marathon and it's 5914292. 147
Let's provide this key as a path parameter to query for this specific activity. 148
So let's open up a new tab and let's structure our request. 149
So first part is the base URL. 150
Next comes the endpoint, which in this case is /activity. 151
So that's the route we're going to hit up using our get request. 152
And then afterwards, after a forward slash, we can specify our unique path parameter. 153
So that's going to go straight into the URL, 154
and it was that number that I told you. 155
So now when I hit send, it's going to look through the database of activities and try to match this 156
key to a specific resource. 157
And once it's found it, it pulls up the entire activity and sends it back to us. 158
And so now we've identified this activity. 159
We've used a GET request to get hold of it, and we use the path parameter to do this. 160
So those are some of the different ways that we can structure our API requests. 161
We've learned about endpoints, we've learned about query parameters, and we've also learned about 162
path parameters. 163
In the next lesson, we're going to learn a little bit more about the structure of the data that comes 164
back from an API request. 165
And when it comes to Web APIs, the format is usually a JSON, so we're going to learn all about that, 166
what it is and how to use it in our code. 167
So for all of that and more, I'll see you there.