1 00:00:00,030 --> 00:00:02,040 Hi and welcome to this video on 2 00:00:02,040 --> 00:00:04,859 improving API documentation. An important 3 00:00:04,859 --> 00:00:06,810 part of API quality is having good 4 00:00:06,810 --> 00:00:09,120 documentation in place. The documentation 5 00:00:09,120 --> 00:00:11,040 helps users know how your API works and 6 00:00:11,040 --> 00:00:13,410 how they can use it. Postman provides a 7 00:00:13,410 --> 00:00:14,610 way for you to create and share 8 00:00:14,610 --> 00:00:16,320 documentation. So let's take a look at 9 00:00:16,320 --> 00:00:20,160 this using this world time API call that 10 00:00:20,160 --> 00:00:21,539 I have here, and I have to find a 11 00:00:21,539 --> 00:00:23,910 location for as Europe and the area here 12 00:00:23,910 --> 00:00:27,029 as London. So we can send this request, 13 00:00:27,029 --> 00:00:30,300 let's go ahead and send that off, and we 14 00:00:30,300 --> 00:00:32,759 get back this response. Now the first 15 00:00:32,759 --> 00:00:33,870 thing that we want to do with our 16 00:00:33,870 --> 00:00:35,670 documentation is get some examples. So 17 00:00:35,670 --> 00:00:37,860 let's go ahead and add an example here, 18 00:00:37,860 --> 00:00:39,870 well at an example and it'll use that 19 00:00:39,870 --> 00:00:42,360 call that we just sent. For our example 20 00:00:42,360 --> 00:00:46,920 let's call it get London time, and then 21 00:00:46,920 --> 00:00:50,309 we'll save this example. So now that we 22 00:00:50,309 --> 00:00:52,079 have this example saved, I'll go ahead 23 00:00:52,079 --> 00:00:53,879 and click on the arrow here beside the 24 00:00:53,879 --> 00:00:57,329 collection, and then we can click on the 25 00:00:57,329 --> 00:01:01,890 first request here and edit it to see 26 00:01:01,890 --> 00:01:04,700 the description. So the description here 27 00:01:04,700 --> 00:01:08,159 has time information, and I've put this 28 00:01:08,159 --> 00:01:09,900 in already to show us this endpoint 29 00:01:09,900 --> 00:01:14,430 takes area and location. Now this is 30 00:01:14,430 --> 00:01:16,380 using something called markdown to 31 00:01:16,380 --> 00:01:18,600 format it, and so the starstar will make 32 00:01:18,600 --> 00:01:21,360 these be bold. You can look there's a lot 33 00:01:21,360 --> 00:01:23,250 of information about how to use markdown 34 00:01:23,250 --> 00:01:25,590 if you want to format your documentation 35 00:01:25,590 --> 00:01:29,189 nicely. So let's go ahead and close this 36 00:01:29,189 --> 00:01:31,049 out, and let's see what it looks like. So 37 00:01:31,049 --> 00:01:32,820 let's click on the view and web button 38 00:01:32,820 --> 00:01:35,490 here, and that brings up the web page for 39 00:01:35,490 --> 00:01:37,829 us. And you can see this web page has the 40 00:01:37,829 --> 00:01:39,720 information that we put, so it's got this 41 00:01:39,720 --> 00:01:42,390 time information these are in bold as we 42 00:01:42,390 --> 00:01:45,960 told it to, and over here is example. So 43 00:01:45,960 --> 00:01:47,399 you can see it's created this example 44 00:01:47,399 --> 00:01:50,399 for us, and it gives us it in see URL, and 45 00:01:50,399 --> 00:01:52,619 it shows you know that how to send the 46 00:01:52,619 --> 00:01:54,600 call with that. And then the example 47 00:01:54,600 --> 00:01:57,299 response that we had saved as well. Now 48 00:01:57,299 --> 00:01:58,829 if we wanted to we could look at it in 49 00:01:58,829 --> 00:02:00,329 other ways, so we could look at it and 50 00:02:00,329 --> 00:02:01,560 Python and see what it would look like 51 00:02:01,560 --> 00:02:04,590 to send this request in Python, and so 52 00:02:04,590 --> 00:02:06,360 this can be a very helpful way for you 53 00:02:06,360 --> 00:02:07,890 to figure out how to do it with the 54 00:02:07,890 --> 00:02:10,560 particular type of system that you're 55 00:02:10,560 --> 00:02:11,550 working with. So if you're working with 56 00:02:11,550 --> 00:02:13,740 jQuery, or node, or PHP you can 57 00:02:13,740 --> 00:02:16,050 generate the requests in an instant, just 58 00:02:16,050 --> 00:02:17,730 copy them from here and use them 59 00:02:17,730 --> 00:02:19,950 directly in the code that you're working 60 00:02:19,950 --> 00:02:22,560 on. Now by default this documentation is 61 00:02:22,560 --> 00:02:25,080 private, but you can also publish it or 62 00:02:25,080 --> 00:02:26,730 share it with your team if you want to, 63 00:02:26,730 --> 00:02:28,770 doing this allows you to create a shared 64 00:02:28,770 --> 00:02:30,870 source of knowledge with your team, and 65 00:02:30,870 --> 00:02:32,220 that's a great way to make sure that 66 00:02:32,220 --> 00:02:35,520 everyone knows how the API works. So in 67 00:02:35,520 --> 00:02:37,350 this video we've learned about how to 68 00:02:37,350 --> 00:02:39,690 create documentation quickly and simply 69 00:02:39,690 --> 00:02:41,700 in Postman. And the next video we'll look 70 00:02:41,700 --> 00:02:43,710 at how we can use Postman to do API 71 00:02:43,710 --> 00:02:48,710 monitoring.