WEBVTT 0 00:00.660 --> 00:07.590 Now in the last lesson we looked at how an API works, at least from the theory point of view. 1 00:07.590 --> 00:13.770 Now in this lesson, I want to talk about how to actually put it into practice and use an API to get some 2 00:13.770 --> 00:16.960 data back from a couple of web sites. 3 00:16.980 --> 00:24.330 Now, when we're talking about APIs, you will often need to think about things including endpoints, paths, 4 00:24.900 --> 00:32.760 parameters, and authentication. These are the four things I want to cover, and we're going to use a few APIs 5 00:33.060 --> 00:36.190 so I can show you what each of these things do. 6 00:36.330 --> 00:44.250 The first thing I want to show you is an API endpoint, and every API that interacts with a external system, 7 00:44.670 --> 00:47.560 like a server, will have an endpoint. 8 00:47.670 --> 00:49.980 So who is this in the photo? 9 00:50.220 --> 00:53.340 Well, it's our friend Kanye Rest. 10 00:53.400 --> 01:00.150 So this is a free REST API for random Kanye West quotes. 11 01:00.480 --> 01:09.960 This web site hosts a database of Kanye West quotes, and we can access the data from this web site by using 12 01:09.990 --> 01:16.560 their API. And the endpoint of the API is this URL right here, 13 01:16.560 --> 01:23.730 api.kanye.rest. And whenever you're using a different API, they're going to likely have a different endpoint, 14 01:24.090 --> 01:30.360 but they'll always tell you what it is in their documentation. Now because this is such a simple API, 15 01:30.420 --> 01:35.520 they've only got one thing that you can do with it, which is to get a random quote. 16 01:35.520 --> 01:39.340 Let's go ahead and see what data we can get from this. 17 01:39.390 --> 01:48.690 So if I take this URL and I paste it into my browser bar, then my browser makes a get request to the 18 01:48.690 --> 01:58.010 kanye.rest server, and they send back a piece of data, which is a quote, and it says, “I hate when”. 19 01:58.770 --> 02:05.580 And the quote is, “I hate when I'm on a flight and I wake up with a water bottle next to me like oh great 20 02:05.580 --> 02:10.030 now I gotta be responsible for this water bottle”. Classic Kanye. 21 02:10.860 --> 02:16.980 Let's say that we created a web site where you could go onto the web site and every day you get a different 22 02:17.340 --> 02:18.590 Kanye quote. 23 02:18.770 --> 02:25.420 Well then you can see that we could probably do that just by using this simple API. 24 02:25.420 --> 02:33.990 Now usually the web sites that have API tend to have more data than just a bunch of random quotes. In 25 02:33.990 --> 02:35.880 addition to endpoints, 26 02:35.910 --> 02:43.800 there’s also API paths and parameters that you can use in order to narrow down on a specific piece of 27 02:43.800 --> 02:49.520 data you want from an external server. In order to illustrate parts and servers, 28 02:49.590 --> 02:57.600 we’re going to use a joke API, which is an API that allow you to access a database of random jokes, and through 29 02:57.600 --> 03:00.000 the use of path and parameters, 30 03:00.090 --> 03:06.200 we’re going to customize the kind of jokes we want to get back. In the course resources, 31 03:06.240 --> 03:13.240 you’ll find a link to the joke API, or you can simply type out this URL. 32 03:13.320 --> 03:18.800 Now this joke API is a little bit more complex than the kanye.rest API. 33 03:18.870 --> 03:25.090 It's more complicated because it has more options for you as the programmer. 34 03:25.140 --> 03:29.580 So, for example, you can choose which category of jokes you want. 35 03:29.580 --> 03:36.360 Do you want any sort of joke or do you want just programming jokes or do you want just dark jokes, or 36 03:36.750 --> 03:39.320 if you wanted to blacklist 37 03:39.330 --> 03:42.690 jokes that are not safe for work, or religious, political. 38 03:42.780 --> 03:50.010 You can change the joke type: a single joke or a two part joke, and you can even search for a particular 39 03:50.010 --> 03:53.650 string that is contained in the joke. 40 03:53.700 --> 03:56.980 So where does all of this customization go 41 03:57.030 --> 04:04.380 if we wanted to implement it? Well firstly, we need to figure out the end point, which is the starting 42 04:04.440 --> 04:05.160 URL. 43 04:05.700 --> 04:12.060 So if we scroll down in the documentation, you can see there's a whole bunch of endpoints, and this end 44 04:12.060 --> 04:15.610 point is the one that you use to get a joke. 45 04:15.660 --> 04:24.570 So the end point looks like this. But notice how if we just put this URL into our browser, you can 46 04:24.570 --> 04:26.640 see we get an error. 47 04:26.640 --> 04:33.390 It says, “No matching joke found”, “The specified category is invalid”. 48 04:33.480 --> 04:34.800 So what's going on here? 49 04:35.880 --> 04:44.190 Well, it's because, even though this is the end point, this is the starting URL, we have to add one other 50 04:44.190 --> 04:48.500 thing to complete it, which is the category or categories of jokes. 51 04:48.540 --> 04:55.740 Now if we go up here and we use the ‘Try it out’ section, you can see that if we chose Any category, it 52 04:55.740 --> 04:58.360 goes to ‘joke/Any’, 53 04:58.470 --> 05:05.420 if we chose just the Programming jokes, so we check that, then it goes to ‘/Programming’. 54 05:05.420 --> 05:13.490 So the difference here is that we need to specify a specific path after the end point. 55 05:13.670 --> 05:20.810 So if we see this as the root of the tree, we have to add a branch. And let's say that our branch was 56 05:20.810 --> 05:23.170 the Programming branch. 57 05:23.270 --> 05:30.050 So now it's going to give us a random programming joke, and it's a two part joke. 58 05:30.050 --> 05:37.440 “Why did the functional programming developer get thrown out of school?” “Because he refused to take classes.” 59 05:37.460 --> 05:41.350 Well, that's a really bad joke. 60 05:41.500 --> 05:47.230 Now we're introducing this concept of paths when we're trying to access an API. 61 05:47.630 --> 05:54.170 And notice how the end point is the URL up to that last forward slash, 62 05:54.350 --> 06:00.320 and then if we went down the Programming path, then we would only be getting programming jokes, but if 63 06:00.320 --> 06:06.810 we change the category to Dark, then we would only be getting jokes from the Dark category. 64 06:06.920 --> 06:13.010 Now remember when we were learning about Node and creating our backend, we know that in order to create 65 06:13.070 --> 06:17.450 a new path, we have to plan for it ahead of time. 66 06:17.450 --> 06:25.370 So somewhere on this joke API server, they have to be able to catch when a request is made to this 67 06:25.370 --> 06:32.540 URL/Programming path, and then filter through all of their jokes and give us a random programming 68 06:32.540 --> 06:33.800 joke. 69 06:33.800 --> 06:41.270 Now sometimes we might want to get a piece of data from an API that is something that they can't plan 70 06:41.270 --> 06:41.600 for. 71 06:42.110 --> 06:51.080 So, for example, if I wanted to search for a joke that contains a specific word, let's say I wanted a programming 72 06:51.080 --> 06:54.820 joke that contained the word ‘debugging’, 73 06:55.040 --> 06:58.520 well then they probably wouldn't have thought of this ahead of time. 74 06:58.520 --> 07:03.710 They probably don't have a path to address this specific query, 75 07:03.710 --> 07:12.440 so in order to allow the API to be flexible enough to deal with custom queries like this, usually APIs 76 07:12.440 --> 07:21.500 allow you to provide parameters. And parameters go at the end of the URL, after a question mark, 77 07:22.100 --> 07:23.080 like this. 78 07:23.420 --> 07:27.880 And then there's a key value pair that goes into the URL. 79 07:27.950 --> 07:30.230 The key is called ‘contains’, 80 07:30.560 --> 07:33.300 so that's basically our search string. 81 07:33.650 --> 07:37.360 And then after an equal sign is the query. Notice 82 07:37.370 --> 07:40.700 that’s exactly what I typed in in here. 83 07:40.730 --> 07:47.060 Now in this ‘Try it out’ section here, you'll notice that there are other parts which are also queries. 84 07:47.060 --> 07:53.390 For example, if I wanted to blacklist all the Not Safe For Work jokes, then you can see that that is a 85 07:53.420 --> 07:58.040 blacklist flag, and then it's equal to ‘not safe for work’. 86 07:59.060 --> 08:07.040 And if I wanted to get rid of all the two part jokes from the jokes that I get back, then we have a type 87 08:07.190 --> 08:08.810 equals ‘single’. 88 08:08.930 --> 08:11.930 And notice how if we have more than one query, 89 08:11.960 --> 08:17.930 so here we've got one, two and three queries, 90 08:17.930 --> 08:26.060 the first query follows a question mark, and every subsequent query follows an ampersand, or an and symbol, 91 08:26.180 --> 08:35.460 like this. So when you want to specify a parameter, remember that you need these symbols in the URL 92 08:35.470 --> 08:37.310 to be able to do that. 93 08:37.390 --> 08:44.350 The parameters come after a question mark, and then they are set as a key value pair with an equal sign 94 08:44.350 --> 08:45.430 in between. 95 08:45.430 --> 08:51.280 And if you want to have more than one parameter, you separate each of the key value pairs with an ampersand 96 08:51.280 --> 09:00.050 symbol. Let’s see what we get if we go ahead and use this particular request. 97 09:00.050 --> 09:06.470 So I'm going to paste that into my browser, and I'm going to make this request from my browser to the 98 09:06.470 --> 09:07.910 joke API server. 99 09:08.480 --> 09:16.910 So I've got the category which is ‘Programming’, because I've used that ‘Programming’ path there, and then 100 09:16.970 --> 09:20.720 I've blacklisted all the jokes that are not safe for work, 101 09:20.720 --> 09:26.720 I have specified that I only want a single part joke, and I want something that contained the word 102 09:26.750 --> 09:28.160 ‘debugging’. 103 09:28.160 --> 09:35.660 So this is the joke I get back. “The six stages of debugging: 1. That can’t happen. 2. That doesn't happen 104 09:35.660 --> 09:37.450 on my machine. 3. 105 09:37.610 --> 09:40.170 That shouldn't happen. 4. 106 09:40.550 --> 09:41.870 Why does that happen? 107 09:41.980 --> 09:45.050 5. Oh, I see. 6. Man, 108 09:45.050 --> 09:47.420 how did that ever work?” 109 09:47.420 --> 09:54.860 So now you can see, through the use of paths and parameters, we’re able to narrow down on the data that 110 09:54.860 --> 10:01.310 we get back from the joke API to the precise thing that we want. 111 10:01.310 --> 10:08.570 Now that you've seen basic APIs in action, and you've seen how we can use paths and parameters to get 112 10:08.570 --> 10:11.600 specific pieces of data from an API, 113 10:11.690 --> 10:15.140 I want you to have a play around with the joke API. 114 10:15.140 --> 10:21.800 Take a look down at the documentation, see what sorts of things that we can get back from the API, and 115 10:21.800 --> 10:27.150 try formatting your URLs and to make some requests using your browser. 116 10:27.380 --> 10:34.490 So if you wanted to get a joke that contains the word ‘arrays’, or say if you wanted to see which categories 117 10:34.550 --> 10:41.840 are available from the joke API, have a play around with it, and make sure that you understand what's 118 10:41.840 --> 10:49.130 going on here when we're typing out this long URL. Pause the video now and try to give that a go. On 119 10:49.130 --> 10:55.340 the next lesson, we're going to talk more about authentication and decoding some of this data that we 120 10:55.340 --> 10:59.360 get back. Pause the video now and give that challenge a go.