1 00:00:00,673 --> 00:00:02,362 - [Instructor] Hi and welcome back to the course. 2 00:00:02,362 --> 00:00:03,771 In this video, we're going to look 3 00:00:03,771 --> 00:00:06,688 at test first design for Rest APIs. 4 00:00:07,699 --> 00:00:12,206 Test first design is not only a technical thing. 5 00:00:12,206 --> 00:00:15,049 It's gonna help designing our APIs better 6 00:00:15,049 --> 00:00:18,198 and it's gonna make software development more efficient 7 00:00:18,198 --> 00:00:20,189 but it's not only a technical thing. 8 00:00:20,189 --> 00:00:22,357 It's also a matter of designing 9 00:00:22,357 --> 00:00:25,318 and creating the right thing. 10 00:00:25,318 --> 00:00:27,496 So what do I mean with this? 11 00:00:27,496 --> 00:00:30,653 Well, let's first begin by going to our collection 12 00:00:30,653 --> 00:00:33,986 and creating a new folder for Section 4. 13 00:00:35,330 --> 00:00:38,039 In this folder, we're going to put the requests 14 00:00:38,039 --> 00:00:40,789 that this API is going to expect. 15 00:00:41,945 --> 00:00:44,703 Now, the thing about thinking about 16 00:00:44,703 --> 00:00:46,953 what request your API needs 17 00:00:48,802 --> 00:00:52,125 is that it forces you to identify 18 00:00:52,125 --> 00:00:55,868 what need there is for each of these requests. 19 00:00:55,868 --> 00:01:00,109 Now, for some of you that might sound obvious or silly 20 00:01:00,109 --> 00:01:04,487 but a lot of people just start making endpoints 21 00:01:04,487 --> 00:01:09,313 before even realising whether they're necessary or not. 22 00:01:09,313 --> 00:01:13,722 So let's imagine that we have a simple API that deals 23 00:01:13,722 --> 00:01:16,616 with storing items in a store. 24 00:01:16,616 --> 00:01:18,354 So we've looked at this in the last section. 25 00:01:18,354 --> 00:01:19,748 We're going to make this 26 00:01:19,748 --> 00:01:22,682 a bit professional in this section 27 00:01:22,682 --> 00:01:26,349 to help introduce the new library as well. 28 00:01:26,349 --> 00:01:29,705 So imagine we've got an API that deals with items. 29 00:01:29,705 --> 00:01:32,962 More sort of operations might we need. 30 00:01:32,962 --> 00:01:35,129 Well, we might need to get 31 00:01:36,677 --> 00:01:39,144 all of the items that are available. 32 00:01:39,144 --> 00:01:42,068 So I would say something like GET, 33 00:01:42,068 --> 00:01:46,235 http://127.0.0.1:5000/items. 34 00:01:47,865 --> 00:01:49,365 I might save that. 35 00:01:50,284 --> 00:01:51,367 So save that. 36 00:01:52,343 --> 00:01:56,215 I'm going to save it as /items. 37 00:01:56,215 --> 00:02:00,382 Then write a short description for what this will return. 38 00:02:01,423 --> 00:02:05,340 This should return a list of items dictionaries 39 00:02:06,410 --> 00:02:08,827 or items each in JSON format. 40 00:02:12,215 --> 00:02:14,716 Now, we can write maybe something like that. 41 00:02:14,716 --> 00:02:16,748 It can be more specific into the description 42 00:02:16,748 --> 00:02:18,432 if you have a better ideas 43 00:02:18,432 --> 00:02:20,127 to what you'd like this to return. 44 00:02:20,127 --> 00:02:21,947 Then save it to the correct place 45 00:02:21,947 --> 00:02:24,197 which in this case is here. 46 00:02:25,371 --> 00:02:26,390 Okay. 47 00:02:26,390 --> 00:02:27,837 So we're gonna want to request 48 00:02:27,837 --> 00:02:31,395 a list of the items that we've got. 49 00:02:31,395 --> 00:02:34,686 We might also want to request a specific item. 50 00:02:34,686 --> 00:02:37,438 So I'm gonna duplicate this thing here 51 00:02:37,438 --> 00:02:39,676 and then request the specific item. 52 00:02:39,676 --> 00:02:43,843 Now there are few options for accessing a specific item. 53 00:02:44,866 --> 00:02:47,091 We may wanna access it by name 54 00:02:47,091 --> 00:02:49,174 such as chair or piano or 55 00:02:50,782 --> 00:02:53,115 GXL3000 which is microphone, 56 00:02:54,047 --> 00:02:55,863 you know, anything else. 57 00:02:55,863 --> 00:02:58,240 We might also wanna access them by ID 58 00:02:58,240 --> 00:02:59,907 like 1234 and so on. 59 00:03:02,083 --> 00:03:04,234 So here it might be a good point in time to decide 60 00:03:04,234 --> 00:03:08,983 whether your items are going to have unique names or not. 61 00:03:08,983 --> 00:03:11,182 Either items are gonna have unique names, 62 00:03:11,182 --> 00:03:14,790 accessing them by name might make sense. 63 00:03:14,790 --> 00:03:17,279 If they may have duplicate names, 64 00:03:17,279 --> 00:03:20,873 then you cannot possibly access one specific item by name 65 00:03:20,873 --> 00:03:25,047 because there may be two items with the same name. 66 00:03:25,047 --> 00:03:28,107 In this case, I'm going to type name here 67 00:03:28,107 --> 00:03:30,347 inside crocodile clips just to remind me 68 00:03:30,347 --> 00:03:32,965 that I'm going to be accessing my items by name 69 00:03:32,965 --> 00:03:37,132 and I meant to replace the items name for this thing here. 70 00:03:38,358 --> 00:03:39,842 So I'm gonna save that. 71 00:03:39,842 --> 00:03:41,342 Then go ahead and edit it 72 00:03:41,342 --> 00:03:44,092 and make sure to change the name. 73 00:03:45,792 --> 00:03:47,792 Then, oops, sorry, name. 74 00:03:48,993 --> 00:03:50,238 The description as well. 75 00:03:50,238 --> 00:03:53,071 This will return one specific item 76 00:03:54,942 --> 00:03:57,609 uniquely identified by its name. 77 00:03:58,613 --> 00:04:01,196 No items may have, no two items 78 00:04:04,934 --> 00:04:06,851 may have the same name. 79 00:04:07,942 --> 00:04:09,420 Okay. 80 00:04:09,420 --> 00:04:11,418 I think as you know we're making decisions 81 00:04:11,418 --> 00:04:14,503 as to how our API is going to be designed. 82 00:04:14,503 --> 00:04:16,221 Now we've realised that each item 83 00:04:16,221 --> 00:04:19,309 is going to have a unique name. 84 00:04:19,309 --> 00:04:21,738 Okay, so what about creating items. 85 00:04:21,738 --> 00:04:23,268 We're probably gonna need to do that 86 00:04:23,268 --> 00:04:25,731 so I'm gonna duplicate this 87 00:04:25,731 --> 00:04:27,898 and change this to a post. 88 00:04:28,741 --> 00:04:32,908 Now think about whether we want to keep this format. 89 00:04:34,471 --> 00:04:37,928 Every item is going to have a unique name 90 00:04:37,928 --> 00:04:41,970 so therefore whenever we make a request like this one, 91 00:04:41,970 --> 00:04:46,076 we're going to essentially be creating a new item. 92 00:04:46,076 --> 00:04:48,698 It makes sense to have the item at the top 93 00:04:48,698 --> 00:04:50,605 because, well you could have it in the body 94 00:04:50,605 --> 00:04:52,566 as well instead if you prefer 95 00:04:52,566 --> 00:04:54,918 but having at the top also makes sense. 96 00:04:54,918 --> 00:04:57,785 After all we're sending data that is 97 00:04:57,785 --> 00:05:01,222 related to one specific items name 98 00:05:01,222 --> 00:05:04,036 and then the body is going to contain information 99 00:05:04,036 --> 00:05:06,869 also required to create that item. 100 00:05:07,897 --> 00:05:11,451 So in the headers I'm going to add Content Type 101 00:05:11,451 --> 00:05:15,338 and it's gonna be application/json. 102 00:05:15,338 --> 00:05:16,299 I save that. 103 00:05:16,299 --> 00:05:18,290 In the body, we're going to go to raw. 104 00:05:18,290 --> 00:05:21,243 Make sure that JSON is selected. 105 00:05:21,243 --> 00:05:24,087 In here, we're going to select what sort of information 106 00:05:24,087 --> 00:05:28,332 our API is going to pass, it's going to receive essentially. 107 00:05:28,332 --> 00:05:30,113 When our request is made, 108 00:05:30,113 --> 00:05:34,253 so what data we want to store for an item? 109 00:05:34,253 --> 00:05:37,401 We might store a price for example. 110 00:05:37,401 --> 00:05:40,353 I'm going to save that to 15.99. 111 00:05:40,353 --> 00:05:44,186 So make sure to save and go ahead and edit it. 112 00:05:45,483 --> 00:05:46,528 That's it. 113 00:05:46,528 --> 00:05:47,548 Now it's a post. 114 00:05:47,548 --> 00:05:48,912 So even though it has the same, 115 00:05:48,912 --> 00:05:53,020 it's a different type and that's what distinguishes them. 116 00:05:53,020 --> 00:05:54,353 Okay, what else? 117 00:05:55,240 --> 00:05:59,083 Well, we may need to be able to delete a specific item. 118 00:05:59,083 --> 00:06:01,744 So once again, I'm going to duplicate this thing here 119 00:06:01,744 --> 00:06:04,526 and I'm going to remove the body 120 00:06:04,526 --> 00:06:07,675 because it's no longer gonna have a content type. 121 00:06:07,675 --> 00:06:09,519 In order to delete sites and what we only need 122 00:06:09,519 --> 00:06:13,246 a unique reference to the item which is a name. 123 00:06:13,246 --> 00:06:16,745 So the only thing we have to do is send a Delete request 124 00:06:16,745 --> 00:06:19,146 for this specific item 125 00:06:19,146 --> 00:06:22,495 and we don't need any headers or any body. 126 00:06:22,495 --> 00:06:24,835 Okay, can I save, make sure to edit that 127 00:06:24,835 --> 00:06:29,721 to remove the copy or sort of to edit descriptions 128 00:06:29,721 --> 00:06:30,927 which I forgot to do. 129 00:06:30,927 --> 00:06:34,510 Delete an item uniquely identified by name. 130 00:06:36,734 --> 00:06:38,871 I'll go back and change the description. 131 00:06:38,871 --> 00:06:40,301 No, I pressed the wrong one. 132 00:06:40,301 --> 00:06:43,148 Change the description here. 133 00:06:43,148 --> 00:06:45,481 This will create a new item. 134 00:06:47,161 --> 00:06:50,578 If the item already exists, it will fail. 135 00:06:52,946 --> 00:06:54,944 Okay, I think that makes sense 136 00:06:54,944 --> 00:06:58,111 for what we're doing here in the post. 137 00:07:00,297 --> 00:07:03,648 However, there is one last thing that we may need 138 00:07:03,648 --> 00:07:07,815 and that is the ability to modify an existing item. 139 00:07:09,043 --> 00:07:11,995 There is a HTTP method for that as we have seen 140 00:07:11,995 --> 00:07:14,120 and that is PUT. 141 00:07:14,120 --> 00:07:18,207 So POST is used to send data to the server 142 00:07:18,207 --> 00:07:21,124 and sort of kind of gathers you with the data. 143 00:07:21,124 --> 00:07:24,543 There you go, give me some new stuff. 144 00:07:24,543 --> 00:07:27,820 PUT is used to give it to the server 145 00:07:27,820 --> 00:07:29,654 and then do one of two things, 146 00:07:29,654 --> 00:07:33,642 either create a new item or update an existing item 147 00:07:33,642 --> 00:07:37,159 that already exists with that unique identifier. 148 00:07:37,159 --> 00:07:40,354 So what I'm going to do is I'm going to duplicate the post. 149 00:07:40,354 --> 00:07:41,856 Change it to PUT. 150 00:07:41,856 --> 00:07:45,042 What's gonna happen now is that the Content Type 151 00:07:45,042 --> 00:07:46,194 is gonna save the same, 152 00:07:46,194 --> 00:07:49,479 the body is gonna change slightly to 17.99. 153 00:07:49,479 --> 00:07:53,023 When we send this request to our API, 154 00:07:53,023 --> 00:07:55,112 it's going to create a new item 155 00:07:55,112 --> 00:07:57,442 with that name and this price 156 00:07:57,442 --> 00:08:00,023 or if that item already exists, 157 00:08:00,023 --> 00:08:04,298 it's going to update that item with a new price. 158 00:08:04,298 --> 00:08:08,518 If we call this 10 times, it would succeed every time 159 00:08:08,518 --> 00:08:10,463 but only the first one would make a difference. 160 00:08:10,463 --> 00:08:13,125 The others would just sort of re-update the item 161 00:08:13,125 --> 00:08:15,070 with the same price every time. 162 00:08:15,070 --> 00:08:18,681 That's why PUT is said to be an important request 163 00:08:18,681 --> 00:08:21,430 because even the thing that you are doing 164 00:08:21,430 --> 00:08:23,654 with this request has already happened, 165 00:08:23,654 --> 00:08:27,144 you can still do the request again and it won't fail. 166 00:08:27,144 --> 00:08:28,504 Okay, make sure to save that 167 00:08:28,504 --> 00:08:30,213 and then go ahead and edit it. 168 00:08:30,213 --> 00:08:32,436 Remove the copy and save. 169 00:08:32,436 --> 00:08:34,822 This will create a new item. 170 00:08:34,822 --> 00:08:39,761 I wanna change that to this will create or a new item 171 00:08:39,761 --> 00:08:42,011 or update an existing item. 172 00:08:44,936 --> 00:08:48,436 We're not gonna fail if it already exists. 173 00:08:49,290 --> 00:08:53,969 Okay, so now we have a better ideas to what we want to do. 174 00:08:53,969 --> 00:08:58,333 For example, we didn't create POST/items 175 00:08:58,333 --> 00:09:01,292 because that's really not necessary now that we know 176 00:09:01,292 --> 00:09:05,745 that we can create single items using this post here. 177 00:09:05,745 --> 00:09:08,206 Similarly, we don't have delete for items. 178 00:09:08,206 --> 00:09:09,490 We're not really gonna wanna delete 179 00:09:09,490 --> 00:09:11,007 all of our items in our database. 180 00:09:11,007 --> 00:09:14,250 Maybe we do wanna do that some point in the future. 181 00:09:14,250 --> 00:09:16,181 So we've got a slightly better ideas 182 00:09:16,181 --> 00:09:19,231 to what our API is going to do. 183 00:09:19,231 --> 00:09:20,840 Now, throughout this section, 184 00:09:20,840 --> 00:09:23,504 I'm going to be adding another endpoint in here 185 00:09:23,504 --> 00:09:25,291 but I'm not gonna do that just now 186 00:09:25,291 --> 00:09:26,770 so as not to confuse you. 187 00:09:26,770 --> 00:09:29,732 That endpoint is going to be related to authentication 188 00:09:29,732 --> 00:09:31,647 and, but we're gonna add that later on. 189 00:09:31,647 --> 00:09:34,387 For now, these five endpoints are all we need. 190 00:09:34,387 --> 00:09:38,677 As you can see, four of them have the exact same format. 191 00:09:38,677 --> 00:09:41,214 They are GET, POST, DEL, and PUT. 192 00:09:41,214 --> 00:09:44,434 And that's going to be one of our resources. 193 00:09:44,434 --> 00:09:45,334 I wanna apologise. 194 00:09:45,334 --> 00:09:48,430 I have to edit these and make sure 195 00:09:48,430 --> 00:09:52,110 to call them /item/name. 196 00:09:52,110 --> 00:09:54,360 That's my badge, like that. 197 00:09:58,920 --> 00:10:00,087 And like that. 198 00:10:01,234 --> 00:10:04,917 So four of them have /item/name. 199 00:10:04,917 --> 00:10:07,002 One of them is /items. 200 00:10:07,002 --> 00:10:10,085 So here we've got two rest resources. 201 00:10:11,078 --> 00:10:13,894 An item in these four requests 202 00:10:13,894 --> 00:10:17,200 and an item list which returns a list of items 203 00:10:17,200 --> 00:10:19,385 in this other request here. 204 00:10:19,385 --> 00:10:23,081 Notice that there are two resources here. 205 00:10:23,081 --> 00:10:25,888 The item list and the item. 206 00:10:25,888 --> 00:10:28,751 They are entirely separate really. 207 00:10:28,751 --> 00:10:31,008 The item is only concerned with one entity 208 00:10:31,008 --> 00:10:32,620 and the items list is concerned 209 00:10:32,620 --> 00:10:36,551 with sort of giving you all of the data that is there. 210 00:10:36,551 --> 00:10:38,263 So when we go to our python application 211 00:10:38,263 --> 00:10:39,487 in the very next video, 212 00:10:39,487 --> 00:10:40,789 we're going to be making sure 213 00:10:40,789 --> 00:10:42,528 that we replicate the structure 214 00:10:42,528 --> 00:10:44,831 by creating two resources. 215 00:10:44,831 --> 00:10:45,867 So that's it for this video. 216 00:10:45,867 --> 00:10:48,597 Thanks for watching and I'll see you on the next one.