1 00:00:01,380 --> 00:00:04,560 Instructor: The next and last part of the URL 2 00:00:04,560 --> 00:00:06,720 is the Query Parameters. 3 00:00:06,720 --> 00:00:10,409 So what are query parameters and when should we use them? 4 00:00:10,409 --> 00:00:13,320 So the query parameters are used to query 5 00:00:13,320 --> 00:00:16,500 the entities in GET method. 6 00:00:16,500 --> 00:00:18,720 Now you might be wondering why do we need 7 00:00:18,720 --> 00:00:21,690 query parameters when we have the ID parameter 8 00:00:21,690 --> 00:00:25,110 which is also used to query the entities 9 00:00:25,110 --> 00:00:27,330 and return a single entity. 10 00:00:27,330 --> 00:00:29,430 So keep this question in mind. 11 00:00:29,430 --> 00:00:30,930 We will come back to it later. 12 00:00:31,830 --> 00:00:35,070 The query parameters come at the end of the URL 13 00:00:35,070 --> 00:00:40,070 after a question mark and they are concatenated with &. 14 00:00:41,460 --> 00:00:44,223 For example, it might look like this. 15 00:00:45,300 --> 00:00:49,710 Note that after the orders entity we have a question mark 16 00:00:49,710 --> 00:00:51,690 and then two parameters. 17 00:00:51,690 --> 00:00:55,410 One is fromDate, with some date 18 00:00:55,410 --> 00:00:59,657 and the other is toDate, with some other date. 19 00:00:59,657 --> 00:01:03,360 So you can understand that what we are trying to do here 20 00:01:03,360 --> 00:01:06,510 is fetch all the orders that were made 21 00:01:06,510 --> 00:01:11,510 between the fromDate parameter and the toDate parameter. 22 00:01:12,150 --> 00:01:14,220 So let's discuss the main differences 23 00:01:14,220 --> 00:01:17,010 between query parameters and ID parameter 24 00:01:17,010 --> 00:01:18,933 and when should we use each one? 25 00:01:19,950 --> 00:01:24,690 So first, the location of them is different. 26 00:01:24,690 --> 00:01:26,550 As we said, query parameters 27 00:01:26,550 --> 00:01:28,440 come at the end of the URL 28 00:01:28,440 --> 00:01:31,110 and the ID parameter comes at the end 29 00:01:31,110 --> 00:01:33,360 or in the middle of the url, 30 00:01:33,360 --> 00:01:36,000 depends if you have a sub entity. 31 00:01:36,000 --> 00:01:38,280 Now how many parameters can I use 32 00:01:38,280 --> 00:01:40,800 with each one of the parameter types? 33 00:01:40,800 --> 00:01:42,510 So with query parameters, 34 00:01:42,510 --> 00:01:45,952 I can use each number between zero and whatever, 35 00:01:45,952 --> 00:01:49,500 and with the ID parameter, I can use only one parameter. 36 00:01:49,500 --> 00:01:52,590 Now if you remember the examples that we discussed 37 00:01:52,590 --> 00:01:54,900 then remember that with query parameters 38 00:01:54,900 --> 00:01:57,150 we really used two parameters. 39 00:01:57,150 --> 00:01:58,793 The fromDate and the toDate. 40 00:01:58,793 --> 00:02:02,400 And the ID parameter is naturally only one parameter 41 00:02:02,400 --> 00:02:04,740 because it specify a single entity. 42 00:02:04,740 --> 00:02:07,015 It'll always be the ID 43 00:02:07,015 --> 00:02:10,530 of the specific entity we want to retrieve. 44 00:02:10,530 --> 00:02:12,870 Now here are examples of using 45 00:02:12,870 --> 00:02:15,000 the query parameters and the ID parameter. 46 00:02:15,000 --> 00:02:18,240 And we already discussed the way these parameters are used, 47 00:02:18,240 --> 00:02:21,330 and here is the most important difference 48 00:02:21,330 --> 00:02:23,640 between query parameters and the ID parameter, 49 00:02:23,640 --> 00:02:25,623 and this is the return value. 50 00:02:26,490 --> 00:02:28,530 With query parameters, 51 00:02:28,530 --> 00:02:32,250 we may get back some unknown numbers of entity. 52 00:02:32,250 --> 00:02:33,960 It could be nothing, it could be one 53 00:02:33,960 --> 00:02:38,160 it could be two, it could be infinity, in theory, of course. 54 00:02:38,160 --> 00:02:39,780 With the ID parameter, 55 00:02:39,780 --> 00:02:44,100 we must return exactly one entity 56 00:02:44,100 --> 00:02:47,790 and note the must in this sentence. 57 00:02:47,790 --> 00:02:49,560 The whole idea of the ID parameter 58 00:02:49,560 --> 00:02:54,450 is that the entity exists and therefore I must return it. 59 00:02:54,450 --> 00:02:57,030 There is no way that using the ID parameter, 60 00:02:57,030 --> 00:02:58,650 no entity is returned. 61 00:02:58,650 --> 00:03:02,460 So what happens when no entities are found using 62 00:03:02,460 --> 00:03:05,460 query parameters or using the ID parameter? 63 00:03:05,460 --> 00:03:07,740 So with the query parameters, that's fine. 64 00:03:07,740 --> 00:03:10,410 We already said that query parameters 65 00:03:10,410 --> 00:03:12,870 may return entities and may not. 66 00:03:12,870 --> 00:03:16,260 Remembering our example with the fromDate and toDate, 67 00:03:16,260 --> 00:03:18,810 there may be no orders at all that were made 68 00:03:18,810 --> 00:03:20,040 between those dates. 69 00:03:20,040 --> 00:03:23,686 And it's perfectly fine if no entity will be returned. 70 00:03:23,686 --> 00:03:26,640 But if I specify an ID parameter 71 00:03:26,640 --> 00:03:29,340 and there is no entity with this ID 72 00:03:29,340 --> 00:03:31,473 then the server should return an error. 73 00:03:32,340 --> 00:03:34,890 Whatever we will see later in the section 74 00:03:34,890 --> 00:03:36,210 about the response codes. 75 00:03:36,210 --> 00:03:37,593 But it is an error. 76 00:03:38,610 --> 00:03:42,543 Okay, so now let's see how to use query parameters. 77 00:03:43,410 --> 00:03:46,050 So back to Beeceptor. 78 00:03:46,050 --> 00:03:48,540 We would like to add a parameter that says 79 00:03:48,540 --> 00:03:51,000 what is the first letter of the item 80 00:03:51,000 --> 00:03:52,920 that we want to retrieve. 81 00:03:52,920 --> 00:03:55,080 So we will do something like this. 82 00:03:55,080 --> 00:03:56,080 Question mark 83 00:03:57,060 --> 00:03:59,080 starts with 84 00:04:00,060 --> 00:04:01,890 equal a. 85 00:04:01,890 --> 00:04:05,760 So what you basically do here is asking the API 86 00:04:05,760 --> 00:04:10,530 to bring us all the items of order number 17 87 00:04:10,530 --> 00:04:13,623 that start with the letter a. 88 00:04:15,090 --> 00:04:18,480 Okay, so now we have a complete URL 89 00:04:18,480 --> 00:04:21,003 and let's test it using Postman. 90 00:04:21,899 --> 00:04:24,970 So I'll just copy it 91 00:04:27,390 --> 00:04:30,690 and let's modify the response 92 00:04:30,690 --> 00:04:33,570 that we're expecting from this API. 93 00:04:33,570 --> 00:04:36,554 And let's build a JSON construct 94 00:04:36,554 --> 00:04:39,453 that contains some data about the items. 95 00:04:40,590 --> 00:04:43,480 So we'll do it like this items 96 00:04:45,030 --> 00:04:49,263 and this would be an array of items. 97 00:04:50,177 --> 00:04:51,757 So item 98 00:05:02,401 --> 00:05:03,630 name. 99 00:05:03,630 --> 00:05:07,680 Now remember we ask for items that begin with letter a. 100 00:05:07,680 --> 00:05:09,960 So we will do just that. 101 00:05:09,960 --> 00:05:14,960 The name of this item will be Artwork. 102 00:05:15,630 --> 00:05:18,927 I always loved this word. 103 00:05:18,927 --> 00:05:22,323 And let's give it also an ID, 104 00:05:24,390 --> 00:05:25,833 which would be 56, 105 00:05:29,850 --> 00:05:31,540 and another one 106 00:05:41,340 --> 00:05:42,173 called 107 00:05:43,950 --> 00:05:44,943 Aircraft, 108 00:05:48,300 --> 00:05:50,200 which has an ID of 109 00:05:53,130 --> 00:05:53,963 123. 110 00:05:58,020 --> 00:06:00,173 And let's close the array 111 00:06:03,867 --> 00:06:08,867 and close the construct and save the rule. 112 00:06:11,970 --> 00:06:16,503 Great, so now let's go to Postman and check this URL. 113 00:06:18,060 --> 00:06:20,850 Okay, so here we are in Postman 114 00:06:20,850 --> 00:06:25,297 and let's paste the URL we built here 115 00:06:26,790 --> 00:06:31,243 and modify the verb to GET 116 00:06:33,270 --> 00:06:37,143 and let's hit Send and see what happens. 117 00:06:39,630 --> 00:06:43,110 And this is exactly what we expected to see. 118 00:06:43,110 --> 00:06:46,800 We see the JSON that we defined in Beeceptor. 119 00:06:46,800 --> 00:06:49,020 We got it back just as expected 120 00:06:49,020 --> 00:06:52,890 as a response for the URL that we used. 121 00:06:52,890 --> 00:06:54,600 Now notice something interesting? 122 00:06:54,600 --> 00:06:58,440 Do you see the green dot here, near Params? 123 00:06:58,440 --> 00:07:03,180 Click it and you see that Postman pass the URL 124 00:07:03,180 --> 00:07:05,220 And so there is a parameter here, 125 00:07:05,220 --> 00:07:06,053 this startsWith, 126 00:07:07,790 --> 00:07:11,940 so it shows us there is a parameter with the key startsWith, 127 00:07:11,940 --> 00:07:14,220 and the value a. 128 00:07:14,220 --> 00:07:15,180 Okay, great. 129 00:07:15,180 --> 00:07:18,870 So we have learned how to construct a simple, 130 00:07:18,870 --> 00:07:23,010 readable, and very easy to use REST API url. 131 00:07:23,010 --> 00:07:24,990 And I hope you understand the importance 132 00:07:24,990 --> 00:07:29,340 of building such a URL and the various components of it. 133 00:07:29,340 --> 00:07:31,710 But before we conclude this section 134 00:07:31,710 --> 00:07:34,593 there is another topic that we need to discuss.