Intro to APIs in Python - API Series #1

hi welcome to the video we're doing something slightly different this time we are going to put together a series of videos just covering apis what apis are how we interact with them how we build them and we will have a look at a few different python frameworks that we use for putting them together now what i have tries to visualize here is how we can think of apis so api uh to start with sums for application program interface and we can think of apis as a black box so this thing in the middle here is our api now inside this magical black box uh what we do is we send data to it over here and all we really know is that it sends data back to us over here now in reality this um this api here is a script on a server somewhere and what it is doing is acting as a middleman or a gatekeeper between us and the server that it represents now through this api we can typically download or get information uh we can request to change some information over on the server or we can request to delete information on server and most requests we can kind of fit into one of those three things for either getting information updating or putting information or deleting information now apis are very structured in that they have a very specific way of working so they generally all follow the same structure and the most common structure out there is called a restful api now a restful api or rest stands for representational state transfer and that sounds really complicated in reality it's it's very straightforward you don't really need to go into too much depth but but it consists of six key factors so we need to follow these six rules in order to make sure our api is restful or a rest api so the first of those is we use a single outward facing interface so there's a single entry point for us to communicate with this api there should be client server independent so like we saw before over here on the left that is the internet and that is where we are coming from over here is a server and what this api does is acts as a middleman between both of those and it allows those two to for example if decline gets updated it will not break the connection between the client and server we just all we need to do is communicate with the api so our communications to the api should not change now if the server is updated and things change on the server the api should remain the same and therefore when we try to communicate with it nothing will change and then we also have statelessness so what this means is say you send a api request and then we send another api request immediately after the results of that second api request should not rely or should not be dependent or change based on the results of the first request unless of course we're changing information changing or deleting information and requesting all that information back again of course in that in that case it will change but the actual state of the api will not change all that's changing there is the underlying data that is hosted on the server is changing but the state of the api does not change it's a blank slate at the start of every new request uh for caching so down here all we're saying here is that the api must it needs to inform us whether it's responses are allowed to be cached by the user the next rule is that the api should follow a layered system structure so there should be a modular structure to this api so one layer can be changed and it should not affect the other layers and finally where it's applicable the api should be able to provide code executable code on request now not all apis 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 so i wouldn't worry too much about that but all of this together for us as general users just means there'll be a single interface for us to interact with the api through and there are a specific set of behaviors that we would expect so we wouldn't expect this api to deviate too much from from any other api now there are a set of different methods that we can interact with an api with so we have a get request which is where we retrieve an information a post request for creating a resource or creating basically creating a new record on the other side of the api we have a put request for updating a resource or record and then we have delete for deleting an existing resource or record now the most commonly used of these is the get requests we use up quite a lot to be honest whenever you want information from an api you use a get request and then if you are interacting with the api in some way there's a database that you're modifying behind it you you're going to use post put and delete quite a lot as well so for example if we wanted to get the gps coordinates from the google maps api we would use the get request so we'd be requesting information alternatively if we were going to use the github api and we wanted to create a repository we wanted to update a repository or wanted to delete a repository we would be using one of those three now there is also another well there are quite a few methods but there is another one that i see online um so i mean the patch request is for partial updates so it's like a request but for partial updates now i've never actually seen this used so i i mean i'm sure it's used somewhere and if you use apis a lot then maybe you'll use it but i think for most users you're probably not going to come across it okay now we've covered how we interact or what requests we send to an api now what about what it returns to us now an api will return different codes depending on the output or the not output the result of whatever it is we we asked it to do so the the first set of codes here are the 200 success codes so anything the two is anything within the 200 range is usually a successor is it's a good thing now we have the most common one which is 200 okay which just means success in general uh 201 we created something or 204 we there's a success but the api didn't return anything it's not necessarily a problem and then we have uh the 400 codes now these are client-side errors so errors on our side and we have the most common uh actually to be honest all these are pretty common uh the one that you mean that you're probably doing something wrong is 400 which is a bad request that means we're entering the request wrong so that might be a the syntax is wrong the form the json format is wrong or we are using the wrong fields in our request and then we have also unauthorized typically it's because we're not authorized ourselves with a authorization key um forbidden so you're trying to access something that you're not allowed to access again that might be because you're unauthorized and you just need to enter your auth key and then you'll be allowed there and then also 404 which is not found that means there's nothing there although some websites like github will use this when there is actually for example a repo there but it's a secret and you're not allowed to see it they'll give you a 404 because otherwise they're telling you hey look this actually exists so they they also give you that sometimes instead of forbidden or unauthorized and then there's also these ones so these are probably the two most important uh client error code so there's uh 418 which is i'm a teapot um and and that's when you know sometimes it happens where you ask a teapot to brew coffee um so in that case just stop doing it and there's also 420 enhance your calm so that's specific to twitter 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 the codes and let's move on to the json object so this is the format we use for interacting with our api it stands for json [Music] object notation and i mean you can probably tell from this if you use python it looks like a dictionary and it pretty much is a dictionary that they use the exact same structure although they're not technically the same but a dictionary is a json like object now it's just a hierarchical format it allows us to use all these different fields we can put lists with strings put more dictionaries inside it so it's it's pretty useful and this is the standard format it's used by everyone for apis now i can show you an example of this so i just come over here i have this little link here so this is actually we're going to go to an api in the browser and make a request from the browser so we we can do that it's not there's nothing weird about doing that and we've gone [Music] to this it's called the pokey api so it's actually an api for pokemon um and it just returns you all this information you can see that i mean it looks pretty messy because it's not in a clean format but this is basically just a dictionary and this is uh this is a json format 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 so we first want to import requests this is just a standard library for making api requests in python it's super easy to use so we just import requests and to make a get request all we need to do is write requests.get and let's use the the pokemon api that we saw before so i'm going to copy this in fact i already copied it no i didn't and so i'm going to copy this and just bring it down here so enter is a string and let me i'm going to saw this in the response variable there and let's see what we get so we get a 200 response so remember before that's what we see over here so it's the 200 okay response so it's good it means it went okay it went well uh but we that's all we see so how do we actually access the json response underneath that uh all we need to do is write json like that so we use the json method that's that's all there is to it so and now we see something very similar to what we've got in the browser before so we have this uh dictionary now we have these abilities i'm not sure exactly what this is returning i think it's just returning why is it returning oh so we're searching for charizard um so charizard has several abilities blaze solar plow solar power and lots of other things forms okay so i'm not sure why you use that but so if we want to access we can access abilities there okay and it goes in to what is now a list so now i need to access first and level of that list and we have this other uh this one entry here go further so you see it's basically just a sort of a tree structure we just keep going deeper and deeper in there and we can let's go let's get the url just curious so i really want to see what what is there so ah okay so it's just another is it is at the api we can see that because it says up here i'll zoom in at pokey api.co and then slash api just very curious i wonder if i can access the website directly like ability66 no we can't okay no problem um yeah so we we have that so maybe that's useful if you're really super into pokemon i don't know maybe like a for a game or something could be useful i'm not sure i think to be honest i think this is more for learning how apis work than anything else uh it's pretty i mean it is pretty useful for this example it's great now i want to show you something that's maybe more relevant so i'm coming over to google and we have the google maps api so documentation here just describes how you access it you can you can follow it along if you want but i'm going to very quickly just go through it so we come down to create api keys go to credentials page you'll probably need to create a project so include that uh it doesn't matter what we call the project so i'm just going to leave it as default name we continue now we have to wait a minute for that to load okay and then this page will load over here so what we want to do is we'll scroll down and we want to use the geocoding api so we click there click enable and once that is loaded want to head over here go to credentials create credentials api key and we just copy this okay so i'm now just going to write that in here so we've got api key copied over from before so there we go um okay need to make sure that is a code cell okay okay so that's the api key and then we also need a few other things so the api url so that is right out here geocode at the end there and then what we're going to do is we're going to enter an address and with that address we're going to return the latitude and longitude from google maps so what we need to do is write requests dot get because we're getting that information in here we want our api address first follow up with json like that and then we want to include the address that we want to search for so we go address equals and then in here we we write that so i'm going to go with the address for the colosseum in rome so piazza del coloro like that now just note that here i've added the plus marks rather than a space if you you can't use spaces in in http requests so i mean you can also use this uh that represents a space but i'm using the the plus signs there and then the last thing actually let me show you what happens if i try and run it like this so let's see okay we get a 200 it's interesting and actually not explained let's see okay so we get 200 requests which is strange i i would have expected i would have expected a like a not unauthorized response maybe but fine so it's just saying so we return this error message saying you must use an api key all right because we we have defined our api key up here but we haven't included in our request so google doesn't know we actually have one so uh we also can include that so we come over here right and key equals and then we have api okay if i know that's not what we it's api key okay now let's have a look what we get so we will check we should still get a 200 response it's good and we also need to make sure that we write https there and again and then we get the all of the address information for the colosseum in rome and if we want so we said we wanted the longitude and latitude so how do we get that we can have a look through it so first thing we do see everything in there so we have results or status okay so let me copy this come down so we have results and the results covers everything from here to well pretty far actually to here so our results is is where we want to go for the long-term latitude because we have the latitude and longitude here so we go to results and then in this case it's a list so we have all these different components here and we want the first entry in that list like so okay so it's just a there's a single entry in in the list i assume they do that if you are requesting multiple addresses i'm not sure and then we want to go into address components okay and then we're in another list again here so we have this one or zero one two three four five so it's dictionary number five i think yeah oh no no no um oh we don't have we don't have the coordinates so let me remove that it's not address components um so we we just went into this list here ah no so we want geometry i think so let's go into geometry okay and then in here we have bounds uh i mean we can just actually no we can go for location it's probably the center i mean i mean these are all obviously going to be very close i don't think the address area for the colosseum is that big so we go location okay and then here we have our coordinates so we can we just save those to chords like so and then within that we would just write chords left i think it was latitude and obviously coordinates long for the longitude like that and there we go we have our coordinates so that's the google geocoding api i like to use that example because the the first sort of coding job i ever had was using this weirdly enough although the code by then was absolutely horrific when i i don't think i have it anymore i'll have to have a look but yeah it was not very not very clean characters it's pretty horrific and the next example so we just that was an example of using the get request but i want to show you also how we can use uh put post or post put and delete as well so um i think the easiest or most popular one player is just github so we will come down here so this is the documentation for getting access to it again link in the description and what we do is we just come down here we come to creating tokens so i'm assuming you have a git hub account um so you just need to make sure everything is verified and it says you need to go into github um and profile photo clip settings so we'll do that okay so i have it open here come over here and go to settings and then over here on the left we want to go down until we see developer settings over here and we want to go to this personal access token so click on there and then we just need to click on this generating token again we just want to click on repo yeah so it's all we need um if you also want to delete i'm not going to do that because it's i think just a bad idea you can you can click delete repo here as well but i'll generate that token and then i i have it down here so i'm going to copy that over into my notebook okay so i've put that in a variable called github key and what i'm going to do here is create a new repository so we're going to send a post request to initialize a new repository um to do that we we also need this other library so import json i'll show you why in a moment and so with jason we'll see in a moment but i'm going to create this dictionary which is going to contain information for my api requests so typically you you would you use this when you're using um posts put delete i think as well so you generally you are going to use this but not so much for get requests so you have the name of the repository which is going to be api test and i'm also going to set it to be public so we can see it and i'm going to say that's true okay and now i'm going to say request.post and then we have the url so it is http s api.github.com so that's user repos and then in the headers so we have this other argument called headers in here we put sort of your authorization typically and any other random little bits of information which is what we're going to use it for so we're going to use it to include our authorization code and you'll typically find that that is formatted in in slightly different way so it's not just a string you also need to include something else so authorization so this is just the uh the parameter name and then here there's an f string i need to put token space and then in here i have my my actual token so github key okay and then this is where we include our payload and why are we using the json package so we write data equals json.dumps so this is essentially going to convert our dictionary here into a json formatted string okay because we can't just include a dictionary in a json request you you will get you'll get an error so you do need to convert that into a json jason string okay that looks pretty good so let's let's try let's see we got we got a four to two response so let's see why repository creation failed because i already have it i've already tested it before apparently so i'm not very creative with my names so we're going to call it api test 2. here we go again uh but notice with with that uh response there we although we haven't covered four two two uh we could see that was a 400 code so we knew that something had gone wrong on our side is a client-side error okay so now okay looks good yeah cool so we have now created a new repository so if i go to my github and have a look i should see that so come over to my github go to repositories and right up there we see this api test too so we did create it and from there we can do other things you can you can post things to your repos you can delete them you just need to modify which permissions you you set when we build up when we create that personal access token so i think that's it for this video i think we covered quite a lot we so we've covered the essentials of apis had a quick look at the pokemon api then the google maps geocoding api and now the github api so i think that's plenty so in the next video what i want to do is have a look at how we can build an api with flask and python so thank you very much for watching and i'll see you next time bye

Channel: James Briggs

Views: 540

Rating: 5 out of 5

Keywords: python, machine learning, data science, artificial intelligence, natural language processing, bert, nlp, nlproc, Huggingface, Tensorflow, pytorch, torch, programming, tutorials, tutorial, education, learning, code, coding, semantic search, similarity search, vector similarity search, vector search

Id: g_yMowQikOE

Length: 28min 24sec (1704 seconds)

Published: Wed Sep 29 2021