Intro to APIs in Python - API Series #1

00:00:00.000 | Hi, welcome to the video. We're doing something slightly different this time

00:00:03.920 | We are going to put together a series of videos just covering

00:00:08.080 | apis

00:00:09.840 | What apis are how we interact with them how we build them?

00:00:13.440 | And we'll have a look at a few different python frameworks that we can use for putting them together

00:00:19.360 | now what I have tried to visualize here is

00:00:24.160 | how we can think of apis so

00:00:27.920 | api

00:00:29.920 | To start with stands for application program interface

00:00:33.860 | And we can think of apis as a black box

00:00:37.920 | So this thing in the middle here is our api now inside this magical black box

00:00:44.160 | What we do is we send data to it over here

00:00:48.400 | And all we really know is that it sends data back to us

00:00:51.920 | over here now

00:00:54.560 | in reality this

00:00:57.280 | This api here is a script on a server somewhere

00:01:02.080 | and

00:01:03.680 | What it is doing is acting as a middleman or a gatekeeper between us

00:01:09.040 | And the server that it represents now through this api we can typically download or get information

00:01:17.380 | We can request to change some information over on the server or we can request to delete information on server

00:01:26.160 | And most requests we can kind of fit into one of those three things

00:01:30.320 | We're either getting information updating or putting information or deleting information now

00:01:36.640 | apis are very

00:01:39.260 | structured in that they have a very

00:01:42.080 | specific way of working so they generally all follow the same structure and the most common

00:01:49.200 | structure out there is called a

00:01:52.880 | RESTful api now

00:01:56.080 | a RESTful api or REST

00:01:58.080 | stands for

00:02:00.700 | Representational state transfer and that sounds really complicated in reality. It is very straightforward. We don't really need to

00:02:08.080 | go into too much depth but

00:02:11.360 | But it consists of six key factors

00:02:15.600 | So we need to follow these six rules in order to make sure our api is RESTful or a REST api

00:02:23.680 | So the first of those is we use a single

00:02:26.480 | Outward facing interface. So there's a single entry point

00:02:30.880 | For us to communicate with this api

00:02:35.680 | There should be client server independent so

00:02:40.400 | Like we saw before over here on the left. That is the internet and that is where we are coming from

00:02:47.680 | Over here is a server

00:02:51.920 | And what this api does is acts as a middleman between both of those and it allows those two to

00:02:58.880 | For example, if the client gets updated

00:03:02.000 | it will not

00:03:04.400 | break the

00:03:05.840 | Connection between the client and server. We just all we need to do is communicate with the api

00:03:10.720 | So our communications to the api should not change

00:03:14.000 | Now if the server is updated and things change on the server the api

00:03:19.760 | Should remain the same and therefore when we try to communicate with it. Nothing will change

00:03:24.320 | and then we also have statelessness, so

00:03:28.000 | What this means is say you send a api request

00:03:33.120 | And then we send other api requests immediately after the results of that second api request

00:03:39.600 | Should not rely or should not be dependent or change based on the results of the first request

00:03:47.440 | unless of course we're changing information changing or deleting information and

00:03:52.400 | Requesting all that information back again, of course in that in that case

00:03:57.200 | It will change but the actual state of the api will not change

00:04:00.480 | All that's changing there is the underlying data that is hosted on the server

00:04:05.520 | Is changing but the state of the api does not change. It's a blank slate

00:04:10.960 | at the start of every new request

00:04:16.160 | For caching so down here all we're saying here is that the

00:04:20.160 | api must

00:04:23.120 | It needs to inform us whether its responses are allowed to be cached by the user the

00:04:30.080 | next rule is that the

00:04:33.680 | Api should follow a layered system structure. So there should be a modular structure to this api

00:04:41.440 | So one layer can be changed and it should not affect the other layers

00:04:45.840 | and

00:04:47.280 | finally where it's applicable

00:04:49.280 | the api

00:04:51.440 | Should be able to provide code executable code on requests now, not all apis

00:04:58.160 | Are relevant for this so we're not going to see this everywhere and as far as I know, it's reasonably rare as well

00:05:04.880 | So I wouldn't worry too much about that

00:05:07.200 | but all of this together for us as

00:05:11.200 | general users just means there'll be a single interface for us to interact with the api through

00:05:15.840 | and

00:05:17.360 | There are a specific set of behaviors that we would expect so we wouldn't expect this api to deviate too much

00:05:24.240 | from

00:05:25.600 | from any other api

00:05:27.600 | Now there are a set of different methods that we can interact with an api with

00:05:33.600 | So we have a get request which is where we retrieve

00:05:38.220 | Information a post request for creating a resource or creating basically creating a new record

00:05:45.340 | On the other side of the api we have a put request for updating a resource or record

00:05:51.580 | And then we have delete

00:05:54.140 | For deleting an existing resource or record

00:05:57.260 | Now the most commonly used of these is the get request we use up

00:06:03.900 | Quite a lot to be honest whenever you want information from an api you use a get request and then if you are

00:06:09.820 | Interacting with the api in some way. There's a database that you're modifying behind it

00:06:13.980 | You're going to use post put and delete quite a lot as well

00:06:17.100 | so for example if we wanted to get the

00:06:20.700 | gps coordinates from the google maps api we would use the get request so we'd be requesting

00:06:29.180 | information

00:06:33.660 | Alternatively if we were going to use the github api and we wanted to

00:06:39.500 | Create a repository we wanted to update a repository or wanted to delete a repository

00:06:44.960 | We would be using

00:06:47.180 | one of those

00:06:48.860 | three

00:06:50.700 | Now there is also another well, there are quite a few methods, but there is another

00:06:55.740 | one that I

00:06:58.460 | See online

00:07:01.100 | Um, so I mean the patch request is for partial updates

00:07:05.740 | So it's like a put request but for partial updates now i've never actually seen this used so i'd

00:07:10.940 | I mean, i'm sure it's used somewhere

00:07:13.500 | And if you use apis a lot, then maybe you'll use it

00:07:16.140 | But I think for most users, you're probably not going to come across it

00:07:19.980 | Okay. Now we've covered how we interact or what?

00:07:26.780 | Requests we send to an api now. What about what it returns to us now?

00:07:31.340 | An api will return different codes depending on the output

00:07:36.700 | or the

00:07:38.860 | not output the

00:07:40.860 | Result of whatever it is. We we asked it to do so

00:07:45.100 | The first set of codes here are the 200 success codes. So anything the two

00:07:51.580 | is

00:07:53.420 | Anything within the 200 range is usually a successor. It's a good thing

00:07:57.580 | now

00:07:59.660 | We have the most common one, which is 200. Okay, which just means success in general

00:08:03.900 | 201 we created something

00:08:06.460 | or 204 we

00:08:08.700 | There's a success but the api didn't return anything. It's not necessarily a problem

00:08:14.540 | and then we have

00:08:17.180 | The 400 codes now. These are client-side errors. So errors on our side

00:08:21.260 | And we have the most common

00:08:24.220 | Actually to be honest. All these are pretty common

00:08:27.180 | the one that you

00:08:29.500 | Means that you're probably doing something wrong is 400 is your bad request. That means we're entering the request wrong. So that might be

00:08:35.820 | A the syntax is wrong the form the json format is wrong

00:08:40.140 | or we are

00:08:43.100 | using the

00:08:45.180 | Wrong fields in our request and then we have also unauthorized typically it's because we're not authorized ourselves with a authorization key

00:08:53.180 | Forbidden so you're trying to access something that you're not allowed to access again

00:08:57.820 | That might be because you're unauthorized and you just need to enter your auth key and then you'll be allowed there

00:09:04.060 | And then also 404 which is not found that means there's nothing there

00:09:08.620 | Although some websites like github will use this

00:09:13.900 | When there is actually for example a repo there, but it's a secret and you're not allowed to see it

00:09:18.860 | They'll give you a 404 because otherwise they're telling you. Hey, look, this is actually exist

00:09:23.180 | So they they also give you that sometimes instead of forbidden or unauthorized

00:09:28.480 | And then there's also these ones. So these are probably the two most important

00:09:33.920 | Client error codes. So there's a 418 which is i'm a teapot

00:09:39.260 | And and that's when you know, sometimes it happens where you ask a teapot to brew coffee

00:09:44.860 | Um, so in that case just stop doing it and there's also 420 enhance your calm. So that's specific to twitter

00:09:51.820 | And that's just saying you really need to chill and because you're sending far too many requests to twitter. Okay, and that's it for

00:09:58.380 | the codes and let's move on to

00:10:02.220 | The json object. So this is the format we use

00:10:06.780 | For interacting with our api. It stands for json

00:10:11.020 | object notation

00:10:14.140 | And it I mean you can probably tell from this if you use python. It looks like a dictionary and it

00:10:19.020 | Pretty much is a dictionary that they use the exact same structure

00:10:23.100 | Although they're not technically the same but dictionary is a json like object

00:10:28.140 | Now it's just a hierarchical format. It allows us to use all these different fields. We can put lists with strings

00:10:35.340 | Put more dictionaries inside it. Uh, so it's it's pretty useful and this is the standard format. It's used by everyone

00:10:42.780 | for apis

00:10:44.860 | Now I can show you an example of this. So I just come over here. I have this little link here. So this is

00:10:50.700 | Actually, we're going to go to an api in the browser and make a request from the browser

00:10:56.220 | So we we can do that. It's not there's nothing weird about doing that and

00:11:00.780 | We've gone

00:11:04.380 | To this it's called the pokey api. So it's actually an api for pokemon

00:11:10.220 | Um, and it just returns you all this information. You can see that. I mean, it looks pretty messy

00:11:15.340 | It's not on a clean format, but this is basically just a dictionary

00:11:18.240 | And this is uh, this is a json format

00:11:21.660 | Now, let's go back to our code and we're going to start putting something together. So we're going to start making some requests

00:11:29.900 | So we first want to import requests, this is just a standard library for making api requests in python

00:11:35.740 | It's super easy to use

00:11:37.260 | So we just import requests and to make a get request. All we need to do is write request dot get

00:11:42.860 | And let's use the the pokemon api that we saw before so i'm going to copy this

00:11:48.700 | In fact, I already copied it. No, I didn't and so i'm going to copy this

00:11:56.940 | And just bring it down here so enter is a string

00:11:59.980 | And let me

00:12:03.500 | I'm going to store this in the response variable there

00:12:07.100 | And let's see what we get so we get a 200 response. So remember before

00:12:12.860 | That's what we see over here, so it's the

00:12:17.340 | 200 okay response so it's good. It means it went. Okay. It went well

00:12:22.460 | Uh, but we that's all we see. So how do we actually access the the json response underneath that?

00:12:28.540 | All we need to do is write json

00:12:31.420 | like that, so

00:12:33.500 | We use the json method and that's that's all there is to it

00:12:36.540 | So now we see something very similar to what we've got in the browser before so we have this

00:12:41.020 | Dictionary now, uh, we have these abilities. I'm not sure exactly what this is returning. I think it's just returning

00:12:49.340 | Why is it returning? Oh, so we're searching for charizard

00:12:52.800 | So charizard

00:12:56.300 | Has several abilities blaze solar power solar power

00:13:01.580 | And lots of other things forms

00:13:05.260 | okay, so

00:13:07.500 | I'm, not sure why you use that but

00:13:09.500 | So if we want to access we can access abilities there

00:13:12.780 | Okay, and it goes in

00:13:15.980 | To what is now a list?

00:13:17.580 | So now we need to access the first end level of that list and we have this other uh, this one entry here

00:13:25.100 | Go further

00:13:27.020 | so you see it's basically just a

00:13:29.100 | Sort of a tree structure. We just keep going deeper and deeper in there

00:13:33.180 | and we can

00:13:35.820 | Let's go

00:13:37.340 | Let's get the url

00:13:39.340 | Just out of curiosity. I really want to see what what is there?

00:13:43.180 | so

00:13:45.260 | Ah, okay

00:13:46.940 | So it's just another is it is the api we can see that because it says up here i'll zoom in

00:13:53.020 | Uh pokie api.co and then slash api

00:13:56.240 | Just very curious I wonder if I can

00:14:00.620 | access the website directly like

00:14:03.100 | Ability 66. No, we can't. Okay. No problem

00:14:07.980 | Um, yeah, so we have that so maybe that's useful if you're really super into pokemon

00:14:16.000 | But I don't know maybe like it for a game or something could be useful

00:14:19.360 | I'm, not sure. I think to be honest. I think this is more for

00:14:22.880 | Learning how apis work than anything else

00:14:26.720 | Uh, it's pretty I mean it's pretty useful for this example. It's great

00:14:31.040 | Now I want to show you something that's maybe more relevant

00:14:36.000 | So i'm coming over to google and we have the google maps api

00:14:41.600 | So documentation here just describes how you access it

00:14:45.200 | You can you can follow it along if you want, but i'm going to very quickly just go through it

00:14:48.960 | So we come down to create api keys go to credentials page. You'll probably need to create a project. So we click that

00:14:55.840 | Uh doesn't matter what we call the project. So i'm just going to leave it with the default name we

00:15:01.120 | continue

00:15:03.680 | Now you have to wait a minute for that to load

00:15:05.840 | Okay, and then this page will load over here. So

00:15:10.320 | What we want to do is we'll scroll down and we want to use the geocoding api. So we click there

00:15:17.040 | click enable

00:15:19.920 | and

00:15:20.960 | Once that is loaded we want to head over here go to credentials

00:15:23.860 | create credentials

00:15:26.960 | Api key and we just copy this

00:15:30.160 | Okay, so i'm now just going to write that in here so we've got api key

00:15:38.640 | Copied it over from before. So there we go

00:15:41.760 | Okay, I just need to make sure that is a code cell, okay

00:15:48.400 | Okay, so that's the api key

00:15:52.160 | And then we also need a few other things so the api url so that is right out here

00:16:01.600 | Geocoded in there

00:16:06.400 | and then what we're going to do is we're going to enter an address and

00:16:10.160 | with that address we're going to return the

00:16:12.960 | Latitude and longitude from google maps. So what we need to do is write requests

00:16:21.120 | Don't get because we're getting that information

00:16:24.900 | In here we want our api address first

00:16:30.000 | Follow that with jason

00:16:33.040 | like that

00:16:34.400 | And then we want to include the address that we want to search for so we go address

00:16:39.600 | Equals and then in here we we write that so i'm going to go with the address for the coliseum in rome

00:16:47.840 | so piazza del

00:16:50.800 | coliseo

00:16:53.340 | Like that now just note that here

00:16:56.640 | i've added the

00:16:58.960 | Plus marks rather than a space if you you can't use spaces in

00:17:03.920 | In http requests, so and you can also use this

00:17:08.720 | that represents a space

00:17:11.520 | but i'm using the

00:17:13.600 | the

00:17:15.280 | plus signs there

00:17:17.120 | And then the last thing in fact, actually, let me show you what happens if I try and run it like this. So let's

00:17:22.480 | see, okay, we get a

00:17:25.200 | 200

00:17:26.720 | It's interesting actually not expected

00:17:29.360 | Let's see

00:17:32.320 | Okay, so we get 200 requests which is strange I would have expected

00:17:43.380 | I would have expected a like a not unauthorized

00:17:48.580 | response maybe

00:17:51.920 | but fine

00:17:54.000 | So it's just saying so we return this error message saying you must use an api key, right?

00:17:59.360 | Because we we have defined our api key up here, but we haven't included it in our request. So google doesn't know we actually have one

00:18:05.360 | so

00:18:07.520 | Uh, we also can include that so we come over here

00:18:10.800 | right and

00:18:13.760 | Key equals then we have api

00:18:16.640 | Okay, I know that's not what we it's api key

00:18:23.360 | Okay

00:18:25.360 | Now let's have a look what we get so we will check we should still get a 200 response. It's good

00:18:31.920 | And we also need to make sure that we write https there

00:18:39.600 | Run that again, and then we get

00:18:43.200 | the

00:18:44.960 | all of the address information for the coliseum in room

00:18:49.040 | and if we want so we said we wanted the longitude and latitude, so how do we get that we

00:18:54.320 | Have a look through it. So

00:18:57.200 | first thing we do

00:18:58.960 | We can see everything in there. So we have results or status

00:19:03.600 | Okay

00:19:06.160 | So, let me copy this come down so we have results and the results covers everything from here

00:19:18.080 | To

00:19:20.080 | Not pretty far actually

00:19:23.520 | Ah to here

00:19:26.560 | So our results is is where we want to go for the longitude latitude because we have the latitude and longitude here

00:19:32.640 | So we go to results

00:19:35.760 | And then in this case, it's a list

00:19:42.960 | So we have all these different

00:19:46.240 | Components here and we want the first entry in that list

00:19:50.080 | Like so

00:19:53.680 | Okay, so it was just a it was a single entry in in the list

00:19:57.120 | I assume they do that if you are requesting multiple addresses

00:20:01.540 | I'm, i'm not sure

00:20:03.360 | And then we want to go into address components

00:20:05.380 | Okay, and then we're in another list again here so we have this one

00:20:16.800 | or zero

00:20:18.240 | one

00:20:20.240 | Two

00:20:22.240 | Three four

00:20:24.960 | Five

00:20:29.040 | so

00:20:30.400 | It's dictionary number five, I think. Yeah. Oh, no, no. No, um

00:20:34.640 | Oh, we don't have we don't have the coordinates. So let me remove that. It's not address

00:20:40.320 | components

00:20:43.920 | So we we just went into this list here

00:20:46.320 | Ah, no, so we want geometry I think

00:20:49.760 | So let's go into geometry

00:20:52.560 | Okay

00:20:56.320 | And then in here we have bounds

00:20:58.400 | Uh, I mean we can just actually no we can go for location. It's probably

00:21:04.640 | Center I mean, I mean these are all obviously going to be very close. I don't think that

00:21:09.840 | address area for

00:21:12.480 | Coliseum is that big

00:21:14.480 | So we go location

00:21:17.040 | Okay, and then here we have our coordinates so we can we just save those to

00:21:23.360 | coords like so

00:21:25.980 | and then

00:21:27.280 | Within there. We would just write coords

00:21:29.760 | Lat I think it was for latitude

00:21:32.720 | And obviously coords long

00:21:35.360 | for the longitude

00:21:38.960 | Like so and there we are. We have our coordinates

00:21:42.340 | so that's the

00:21:44.960 | google

00:21:46.220 | geocoding api

00:21:48.240 | I like to use that example because the the first sort of coding

00:21:52.160 | Job, I ever had was using this weirdly enough

00:21:56.720 | although the code back then was absolutely horrific when I

00:22:00.000 | I I don't think I have it anymore. I'll have to have a look

00:22:03.600 | Uh, but yeah, it was not very not very clean code. It's it's pretty horrific

00:22:09.360 | And the next example, so we just that was an example of using the get request

00:22:14.960 | but I want to show you also how we can use a put post or post put and delete as well, so

00:22:21.600 | um

00:22:23.600 | I think the easiest or most popular one that is just github. So

00:22:28.720 | we will

00:22:30.960 | Come down here. So this is the documentation for getting access to it again link in description

00:22:37.360 | And what we do is we just come down here

00:22:40.480 | We come to create a token. So i'm assuming you have a github account

00:22:46.320 | So you just need to make sure everything is verified and it says you need to go into github

00:22:52.160 | And click profile photo click settings. So we'll do that

00:22:56.720 | Okay, so I have it open here come over here go to

00:23:02.320 | Settings

00:23:05.760 | And then over here on the left we want to go down until we see developer settings over here

00:23:10.960 | And we want to go to this personal access token. So click on there

00:23:15.680 | Uh, and then we just need to click on this generating token

00:23:19.840 | Okay, and we just want to click on repo here. So it's all we need. Um, if you also want to delete i'm not going to

00:23:27.600 | It's I think just a bad idea you can you can click delete repo here as well

00:23:32.800 | But i'll generate that token

00:23:35.760 | And then I have it down here. So i'm going to copy that over into my notebook

00:23:40.980 | Okay, so i've put that in a variable called github key

00:23:45.600 | And what i'm going to do here is

00:23:49.280 | Create a a new repository. So we're going to send a post request

00:23:54.240 | to

00:23:55.740 | Initialize a new repository. Um to do that. We we also need this other

00:24:00.000 | Library, so import json. I'll show you why in a moment

00:24:05.120 | um, so with

00:24:07.120 | json

00:24:09.920 | We'll see in a moment, but i'm going to create this dictionary which is going to contain information for my api requests

00:24:17.120 | So typically you you would you use this when you're using?

00:24:21.600 | post put

00:24:24.320 | delete

00:24:25.600 | Think as well. So you generally you are going to use this but not so much for get requests

00:24:31.920 | So you have the name of the repository which is going to be api test

00:24:36.720 | And i'm also going to set it to be public so we can

00:24:40.080 | See it and i'm going to say that's true

00:24:42.960 | Okay, and now i'm going to say request.post

00:24:46.740 | And then we have the url so it is

00:24:51.920 | htps

00:24:55.420 | api.github.com

00:24:57.420 | user repos

00:25:01.840 | And then in the headers so we have this other

00:25:04.400 | Argument called headers in here. We put

00:25:08.960 | sort of your authorization typically and then any other

00:25:13.360 | random little bits of information

00:25:16.160 | Which is what we're going to use it for so we're going to use it to include our authorization code

00:25:20.800 | and you'll typically find that that is formatted in in

00:25:25.760 | Slightly different ways. It's not just a string. You also need to include something else

00:25:31.520 | so authorization

00:25:33.360 | so this is just the

00:25:35.360 | the

00:25:36.400 | parameter name

00:25:38.400 | And then here there's an f string

00:25:41.040 | I need to put token space and then in here I have my my actual token. So github

00:25:48.240 | key

00:25:50.960 | Okay

00:25:52.960 | And then this is where we include our payload and why we're using the json

00:25:57.840 | Package so we write data equals json.dumps

00:26:03.060 | so this is essentially going to

00:26:05.840 | convert our dictionary here into a json formatted string

00:26:10.720 | Okay, because we can't just include a dictionary in a json request. You you will get you'll get an error

00:26:17.680 | So you do need to convert that into a json json string

00:26:23.760 | Okay

00:26:26.800 | That looks pretty good. So let's let's try it

00:26:28.880 | Let's see we got we got a 422 response, so let's see why

00:26:36.640 | repository

00:26:40.300 | Creation failed because I already have it. I've already tested it before apparently so

00:26:44.560 | I'm, not very creative with my names. So we're going to call it api test 2

00:26:49.120 | Here we go again

00:26:54.560 | Uh, but notice with with that, uh response that we although we haven't covered 422

00:26:59.860 | Uh, we could see that was a 400 code. So we knew that something had gone wrong on our side

00:27:04.880 | All right, is it is a client-side error?

00:27:07.520 | Okay, so now

00:27:10.160 | Okay, it looks good

00:27:12.160 | Yeah, cool so we have

00:27:15.600 | now created a

00:27:18.880 | New repository. So if I go to my github and have a look I should see that

00:27:23.360 | so come over to my

00:27:25.360 | github go to repositories

00:27:28.000 | And right at the top there. We see this api test 2 so we did create it

00:27:34.160 | And from now we can do other things you can you can post things to your repos. You can delete them

00:27:42.080 | You just need to modify which permissions you've set when we build up when we create that personal access token

00:27:50.480 | So I think that's it for this video

00:27:53.680 | I think we've covered quite a lot. We so we've covered the essentials of apis had a quick look at the pokemon api

00:28:01.440 | then the

00:28:03.840 | Google maps geocoding api and now the github api so

00:28:07.760 | I think that's plenty so in the next

00:28:10.960 | Video what I want to do is have a look at how we can build an api

00:28:15.520 | with flask and python

00:28:19.440 | So, thank you very much for watching and I'll see you in the next one. Bye!

Intro to APIs in Python - API Series #1

Chapters