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.