1 00:00:01,100 --> 00:00:04,510 So, our API is now basically finished. 2 00:00:04,510 --> 00:00:07,003 And so in this final video of the section, 3 00:00:07,003 --> 00:00:09,680 we're gonna quickly create documentation 4 00:00:09,680 --> 00:00:13,020 for API directly in Postman. 5 00:00:13,020 --> 00:00:15,290 And that's right, we can easily create 6 00:00:15,290 --> 00:00:18,830 some quick documentation right in Postman. 7 00:00:18,830 --> 00:00:21,620 And it's really important to have API documentation 8 00:00:21,620 --> 00:00:25,870 in place because this is how we communicate to team members, 9 00:00:25,870 --> 00:00:29,140 or even our final users of the API, 10 00:00:29,140 --> 00:00:31,740 how they can actually use it in practice. 11 00:00:31,740 --> 00:00:33,973 So let me now show you how it works. 12 00:00:35,490 --> 00:00:38,367 Now before we can actually create the documentation, 13 00:00:38,367 --> 00:00:40,920 let's just do some clean up here. 14 00:00:40,920 --> 00:00:45,010 For example, get rid of this request, all right? 15 00:00:47,550 --> 00:00:51,490 Another thing that I want to do is here in the logging in 16 00:00:51,490 --> 00:00:55,180 point, we actually expose our password here. 17 00:00:55,180 --> 00:00:58,220 And so that's not a good idea, and so what I'm gonna do 18 00:00:58,220 --> 00:01:00,350 is to create an environment variable 19 00:01:00,350 --> 00:01:02,320 which is going to hold this password. 20 00:01:02,320 --> 00:01:06,100 Since it's always the same that should be no problem. 21 00:01:06,100 --> 00:01:07,833 So, remember how we do that. 22 00:01:09,920 --> 00:01:12,730 Well we come here to managing the environment 23 00:01:13,970 --> 00:01:16,903 and so here we simply add another one. 24 00:01:17,960 --> 00:01:19,807 So password, test1234. 25 00:01:23,820 --> 00:01:28,820 And here this is not correct, so password, updated, 26 00:01:30,220 --> 00:01:31,860 and now, let's do the same here 27 00:01:31,860 --> 00:01:33,363 in the production one as well. 28 00:01:35,440 --> 00:01:37,297 So password, test1234. 29 00:01:41,020 --> 00:01:46,020 And so, not add, but let's close that 30 00:01:46,590 --> 00:01:51,120 and so here I can now then go add and use that, 31 00:01:51,120 --> 00:01:55,003 not in a string, but like this. 32 00:01:56,840 --> 00:01:58,490 So password. 33 00:01:58,490 --> 00:01:59,633 So let's try that. 34 00:02:00,980 --> 00:02:04,620 And this gives us this weird error, 35 00:02:04,620 --> 00:02:07,840 but our password is actually here so probably what 36 00:02:07,840 --> 00:02:12,313 we need to do is to actually really put the quotes here. 37 00:02:13,360 --> 00:02:14,680 So let's try that. 38 00:02:14,680 --> 00:02:17,740 And so now indeed we're successfully logged in. 39 00:02:17,740 --> 00:02:21,090 So save that now, okay? 40 00:02:21,090 --> 00:02:23,990 And so now what we should do is to actually create 41 00:02:23,990 --> 00:02:26,290 a description for each and every request 42 00:02:26,290 --> 00:02:28,150 that we have in our collection. 43 00:02:28,150 --> 00:02:30,120 Now of course I'm not going to do that, 44 00:02:30,120 --> 00:02:33,173 I will just exemplify it here with the first one. 45 00:02:34,270 --> 00:02:35,103 Okay? 46 00:02:36,630 --> 00:02:39,250 So let's actually close these other ones 47 00:02:39,250 --> 00:02:42,840 and so now here we can add a description. 48 00:02:42,840 --> 00:02:46,350 And so let's just say, use this endpoint 49 00:02:49,150 --> 00:02:52,403 to create a new tour. 50 00:02:53,530 --> 00:02:58,514 Okay, and so again, you should now do this exact same thing 51 00:02:58,514 --> 00:03:03,030 for all of your requests if your goal is to really publish 52 00:03:03,030 --> 00:03:06,170 and share your API, okay? 53 00:03:06,170 --> 00:03:09,633 Then the same thing applies to folders, 54 00:03:11,130 --> 00:03:14,300 and to not rename, but to edit. 55 00:03:14,300 --> 00:03:15,900 And so in each of these folders 56 00:03:15,900 --> 00:03:18,870 we can actually also add a description. 57 00:03:18,870 --> 00:03:23,380 So let's just say, something random like, 58 00:03:23,380 --> 00:03:27,093 you can get all tours, 59 00:03:27,960 --> 00:03:29,463 create new ones, 60 00:03:31,400 --> 00:03:34,743 and edit and delete tours. 61 00:03:36,580 --> 00:03:41,000 There are also special endpoints 62 00:03:42,630 --> 00:03:44,763 for some special requirements. 63 00:03:46,170 --> 00:03:48,680 Okay, so and again this is totally random 64 00:03:48,680 --> 00:03:52,350 and I would publish something like this for my own API, 65 00:03:52,350 --> 00:03:56,100 but here we really just want to test how it works, okay? 66 00:03:56,100 --> 00:03:57,540 As you can see down here, 67 00:03:57,540 --> 00:04:00,800 you can also use Mark down here, okay? 68 00:04:00,800 --> 00:04:03,240 So for example, to make text bold, 69 00:04:03,240 --> 00:04:06,273 you can think it works like this, 70 00:04:07,820 --> 00:04:09,920 yeah it looks like it does, 71 00:04:09,920 --> 00:04:13,523 and so yeah you can do all kinds of stuff here, okay? 72 00:04:15,970 --> 00:04:18,730 You can also probably create a description 73 00:04:18,730 --> 00:04:21,500 on Natours itself, so let's say, 74 00:04:21,500 --> 00:04:26,363 the Natours API contains endpoints 75 00:04:30,950 --> 00:04:35,950 for tours, users, and reviews. 76 00:04:37,790 --> 00:04:39,510 And then again a bunch of stuff, 77 00:04:39,510 --> 00:04:42,500 like you could describe your authentication process, 78 00:04:42,500 --> 00:04:45,320 or your permissions and really everything the user needs 79 00:04:45,320 --> 00:04:48,820 to know in order to use this API, okay? 80 00:04:48,820 --> 00:04:50,510 So you should always add description 81 00:04:50,510 --> 00:04:54,060 to all the requests, to all the folders 82 00:04:54,060 --> 00:04:57,490 and also to, of course, the collection itself. 83 00:04:57,490 --> 00:05:01,510 Oh, and we can actually describe the query parameters 84 00:05:01,510 --> 00:05:03,943 in a query string, so let's do that here. 85 00:05:09,634 --> 00:05:13,384 And we can also say it supports greater than, 86 00:05:14,620 --> 00:05:19,620 less than equal, greater than and less than operators. 87 00:05:23,070 --> 00:05:24,890 So again, just an example here 88 00:05:26,070 --> 00:05:28,490 and let's save it now to the request. 89 00:05:28,490 --> 00:05:30,580 And so with this I think we should be ready 90 00:05:30,580 --> 00:05:33,700 to actually publish our API documentation. 91 00:05:33,700 --> 00:05:36,750 And so for doing that, let's just go here 92 00:05:36,750 --> 00:05:39,910 to the collections option, and then down here, 93 00:05:39,910 --> 00:05:42,070 publish documentations. 94 00:05:42,070 --> 00:05:45,400 And so that should then open up a browser window, 95 00:05:45,400 --> 00:05:47,830 and for me it did outside of my screen 96 00:05:47,830 --> 00:05:50,570 so let me just get that here. 97 00:05:50,570 --> 00:05:53,700 And so now you can choose the environment. 98 00:05:53,700 --> 00:05:57,200 So here we should have a list of our environments, 99 00:05:57,200 --> 00:06:01,470 which for some reason we do not have, that's weird, 100 00:06:01,470 --> 00:06:05,060 but anyway, we didn't want to use any environment anyway, 101 00:06:05,060 --> 00:06:06,540 because that would then replace 102 00:06:06,540 --> 00:06:09,340 our environment variables with their real values, 103 00:06:09,340 --> 00:06:10,460 and we don't want that. 104 00:06:10,460 --> 00:06:12,620 For example, we used the environment variable 105 00:06:12,620 --> 00:06:14,620 on the password, so that then later 106 00:06:14,620 --> 00:06:17,900 in the documentation it's not really visible, okay? 107 00:06:17,900 --> 00:06:20,313 So we really want to use no environment. 108 00:06:21,270 --> 00:06:23,280 Now we could also use a custom domain, 109 00:06:23,280 --> 00:06:27,610 but that's only for paid users, okay? 110 00:06:27,610 --> 00:06:30,740 Then we could also change all of the styling 111 00:06:30,740 --> 00:06:34,410 of the API so to match it with your brand colors, 112 00:06:34,410 --> 00:06:37,260 but again, that's not necessary in this case, 113 00:06:37,260 --> 00:06:40,620 and so, let's actually go ahead and publish it. 114 00:06:40,620 --> 00:06:42,550 And so now, this is actually public, 115 00:06:42,550 --> 00:06:46,367 so everyone can view your documentation now on this URL. 116 00:06:47,480 --> 00:06:51,300 Now for some reason it didn't really update all 117 00:06:51,300 --> 00:06:54,653 the changes that we just did before, so that's a bit weird. 118 00:06:55,510 --> 00:06:58,420 So let's actually go back to Postman 119 00:06:58,420 --> 00:07:00,090 and see what's going on. 120 00:07:00,090 --> 00:07:04,510 Maybe it has to do with this rotating thing here, 121 00:07:04,510 --> 00:07:07,158 so I will just quit Postman and open it again. 122 00:07:07,158 --> 00:07:09,393 And let's hope that fixes it. 123 00:07:12,610 --> 00:07:15,060 So if we now reload here, 124 00:07:15,060 --> 00:07:18,720 ahh then we get all our changes actually here. 125 00:07:18,720 --> 00:07:20,980 So you see, the description that we added 126 00:07:20,980 --> 00:07:23,620 for the Natours collection, okay? 127 00:07:23,620 --> 00:07:26,830 Then also the description for this folder, 128 00:07:26,830 --> 00:07:29,530 and the description for this request. 129 00:07:29,530 --> 00:07:32,180 And finally, as the first description, 130 00:07:32,180 --> 00:07:35,400 also for this parameter, okay? 131 00:07:35,400 --> 00:07:39,477 Here we do then get the URL environment variable 132 00:07:39,477 --> 00:07:41,850 instead of the actual URL. 133 00:07:41,850 --> 00:07:44,310 Now of course, you might want to actually give 134 00:07:44,310 --> 00:07:46,320 the real URL here and for that 135 00:07:46,320 --> 00:07:48,443 you could simply use another environment. 136 00:07:50,150 --> 00:07:53,170 So up here you can actually see all the environments 137 00:07:53,170 --> 00:07:57,060 but they are private, so right now no one can use them, 138 00:07:57,060 --> 00:07:58,720 but remember how in the first step, 139 00:07:58,720 --> 00:08:01,430 we could have actually created this documentation 140 00:08:01,430 --> 00:08:04,760 using one of the environments, and so probably we would have 141 00:08:04,760 --> 00:08:07,990 used the production environment for that and so with that 142 00:08:07,990 --> 00:08:11,350 we would then have the final production URL 143 00:08:11,350 --> 00:08:14,543 here in our API URL's, okay? 144 00:08:15,440 --> 00:08:18,064 Anyway, this is how the documentation looks like, 145 00:08:18,064 --> 00:08:21,530 so here is the example request 146 00:08:21,530 --> 00:08:24,940 and we can change that also to our own language. 147 00:08:24,940 --> 00:08:27,840 So in this case, Node JS, but if the user is 148 00:08:27,840 --> 00:08:31,020 for example doing a request using jQuery, 149 00:08:31,020 --> 00:08:34,770 then they can just use jQuery, okay. 150 00:08:34,770 --> 00:08:39,290 So just to see this example request here, so with Node, 151 00:08:39,290 --> 00:08:40,793 it looks something like this. 152 00:08:42,870 --> 00:08:45,213 So, here we have all our endpoints 153 00:08:45,213 --> 00:08:48,400 and you can see that the ones that require authentication, 154 00:08:48,400 --> 00:08:51,400 they actually have this lock icon here. 155 00:08:51,400 --> 00:08:54,299 And so in your description you could now then add that 156 00:08:54,299 --> 00:08:57,960 saying you need to log in, in order to access this endpoint, 157 00:08:57,960 --> 00:09:01,060 and also how you can actually log in, okay. 158 00:09:01,060 --> 00:09:02,760 Or you can also describe that here 159 00:09:02,760 --> 00:09:06,290 in the authentication section, right? 160 00:09:06,290 --> 00:09:09,243 So ideally, you would have descriptions for all of this. 161 00:09:10,360 --> 00:09:11,948 Oh, and here I see that we actually forgot 162 00:09:11,948 --> 00:09:15,770 to replace the real password but nevermind 163 00:09:15,770 --> 00:09:19,940 as this is really just some example, okay? 164 00:09:19,940 --> 00:09:22,040 But of course, you get all the requests 165 00:09:22,040 --> 00:09:24,933 that we had in our Postman also right here. 166 00:09:26,900 --> 00:09:30,780 Now another nice feature here is this run in Postman button, 167 00:09:30,780 --> 00:09:33,830 and so if someone has Postman installed on their computer, 168 00:09:33,830 --> 00:09:36,380 all they need to do is to click here 169 00:09:36,380 --> 00:09:40,000 and then open with their Postman application. 170 00:09:40,000 --> 00:09:42,490 Now I'm not going to do that right now because of course, 171 00:09:42,490 --> 00:09:45,830 I already have it in my Postman, but otherwise 172 00:09:45,830 --> 00:09:49,270 this is a really nice feature for the users to then go ahead 173 00:09:49,270 --> 00:09:52,253 and right away start experimenting with your API. 174 00:09:54,070 --> 00:09:57,370 Okay, and I think that's it actually 175 00:09:57,370 --> 00:09:59,330 so this wraps up our section 176 00:09:59,330 --> 00:10:02,610 and our API is now finally really completed. 177 00:10:02,610 --> 00:10:06,440 So again, congratulations for making it this far 178 00:10:06,440 --> 00:10:08,720 into the course, we've already covered 179 00:10:08,720 --> 00:10:11,140 so much ground here together. 180 00:10:11,140 --> 00:10:14,230 Now next up, there is a very, very exiting section 181 00:10:14,230 --> 00:10:16,460 ahead where we will finally build 182 00:10:16,460 --> 00:10:19,260 the user face for the Natours website. 183 00:10:19,260 --> 00:10:21,510 So basically, we're going to use templates 184 00:10:21,510 --> 00:10:24,770 to create a completely dynamic website based 185 00:10:24,770 --> 00:10:27,810 on all the data that we already have in our database. 186 00:10:27,810 --> 00:10:29,380 And that's really cool. 187 00:10:29,380 --> 00:10:32,053 And so I can't wait to show that to you.