1 00:00:00,480 --> 00:00:03,930 Instructor: So how do we add versioning in the API? 2 00:00:03,930 --> 00:00:08,490 So the version can come in three forms in the API. 3 00:00:08,490 --> 00:00:13,320 The first one is in the URL itself, something like this. 4 00:00:13,320 --> 00:00:15,330 Now at this stage of the course, 5 00:00:15,330 --> 00:00:18,090 you probably feel quite comfortable with this method 6 00:00:18,090 --> 00:00:21,060 because all the samples that we demonstrated 7 00:00:21,060 --> 00:00:24,930 of the REST API included the version in the URL itself. 8 00:00:24,930 --> 00:00:28,350 And actually, when discussing the best practice 9 00:00:28,350 --> 00:00:30,690 for constructing the API URL, 10 00:00:30,690 --> 00:00:33,420 we explicitly mentioned the version 11 00:00:33,420 --> 00:00:37,358 as a component that must be included in the URL. 12 00:00:37,358 --> 00:00:38,191 So this is one 13 00:00:38,191 --> 00:00:41,973 of the most common forms of versioning in the API. 14 00:00:43,437 --> 00:00:47,310 Another form is to put the version in the header, 15 00:00:47,310 --> 00:00:48,663 something like this. 16 00:00:49,710 --> 00:00:51,480 So if you see here, 17 00:00:51,480 --> 00:00:54,360 the URL itself does not contain the version. 18 00:00:54,360 --> 00:00:57,300 You can see at the top row of the example 19 00:00:57,300 --> 00:00:59,940 that the URL contains only users, 20 00:00:59,940 --> 00:01:01,200 and the number three, 21 00:01:01,200 --> 00:01:03,930 which is probably some kind of an ID. 22 00:01:03,930 --> 00:01:06,870 The accept header contains the version 23 00:01:06,870 --> 00:01:08,670 that the client is using. 24 00:01:08,670 --> 00:01:11,010 In this case, v1. 25 00:01:11,010 --> 00:01:13,590 So this is another method. 26 00:01:13,590 --> 00:01:16,230 And the last one is to put the version 27 00:01:16,230 --> 00:01:19,170 in a query parameter like this. 28 00:01:19,170 --> 00:01:21,900 So you see here that the URL itself, the base URL, 29 00:01:21,900 --> 00:01:24,750 does not contain the version, but the version comes 30 00:01:24,750 --> 00:01:27,540 as a query parameter after the question mark. 31 00:01:27,540 --> 00:01:29,643 In this case, this is version4. 32 00:01:31,500 --> 00:01:33,720 So these are the three forms 33 00:01:33,720 --> 00:01:36,870 of specifying the version in the API. 34 00:01:36,870 --> 00:01:39,570 Now, the question of course, is which one to use? 35 00:01:39,570 --> 00:01:41,490 Which form of versioning 36 00:01:41,490 --> 00:01:44,400 is the one we should pick with our API? 37 00:01:44,400 --> 00:01:47,880 So the header form is the most correct form. 38 00:01:47,880 --> 00:01:51,000 And the reason for that is that putting the version 39 00:01:51,000 --> 00:01:54,060 in the header adheres to the REST principles. 40 00:01:54,060 --> 00:01:56,460 Now what this means is this. 41 00:01:56,460 --> 00:01:59,460 If you remember when discussing the REST principle, 42 00:01:59,460 --> 00:02:02,970 we said that REST is an actual representation 43 00:02:02,970 --> 00:02:05,100 of a resource of an entity, 44 00:02:05,100 --> 00:02:07,710 so that when looking at a URL, 45 00:02:07,710 --> 00:02:12,120 we know that this URL is the identity of a resource. 46 00:02:12,120 --> 00:02:14,640 Now, putting the version in the URL 47 00:02:14,640 --> 00:02:17,910 is in some way contamination of the URL, 48 00:02:17,910 --> 00:02:20,040 because putting the version in the URL 49 00:02:20,040 --> 00:02:22,620 means that there is an additional information 50 00:02:22,620 --> 00:02:26,010 in the URL besides the identity of the resource. 51 00:02:26,010 --> 00:02:28,830 And this is not what REST is all about. 52 00:02:28,830 --> 00:02:31,050 So according to the REST principles, 53 00:02:31,050 --> 00:02:34,200 the URL must represent only an entity 54 00:02:34,200 --> 00:02:37,380 and not any additional information. 55 00:02:37,380 --> 00:02:39,750 So from the best practices point of view, 56 00:02:39,750 --> 00:02:42,210 the version should come in the header. 57 00:02:42,210 --> 00:02:47,210 However, URL is the most common and easiest to implement, 58 00:02:47,280 --> 00:02:48,120 and this is also 59 00:02:48,120 --> 00:02:52,260 the reason why we specified the version in the URL. 60 00:02:52,260 --> 00:02:53,610 As you saw for yourself, 61 00:02:53,610 --> 00:02:57,030 integrating the version in the URL is extremely easy, 62 00:02:57,030 --> 00:02:59,790 it requires no additional development effort, 63 00:02:59,790 --> 00:03:03,810 and it also makes the URL very self explanatory. 64 00:03:03,810 --> 00:03:06,360 So when a developer will look at the URL, 65 00:03:06,360 --> 00:03:09,090 she will know immediately what is the version 66 00:03:09,090 --> 00:03:12,390 of the API this URL is referring to. 67 00:03:12,390 --> 00:03:15,210 Now whatever method you will choose, 68 00:03:15,210 --> 00:03:17,610 do not use query parameters. 69 00:03:17,610 --> 00:03:20,397 They query parameters method is the worst one. 70 00:03:20,397 --> 00:03:24,120 And this is also the reason why almost nobody is using it. 71 00:03:24,120 --> 00:03:28,610 So refrain from using query parameters for versioning. 72 00:03:28,610 --> 00:03:30,240 So the bottom line is this. 73 00:03:30,240 --> 00:03:34,230 In order to implement and integrate versioning in your API, 74 00:03:34,230 --> 00:03:38,910 put the version either in the header or in the URL, 75 00:03:38,910 --> 00:03:41,430 and never in the query parameters. 76 00:03:41,430 --> 00:03:43,440 Now between the header and the URL, 77 00:03:43,440 --> 00:03:47,190 practically, whatever method you will choose will be fine. 78 00:03:47,190 --> 00:03:50,580 And of course, always specify the version. 79 00:03:50,580 --> 00:03:53,850 You have to have a well defined versioning policy 80 00:03:53,850 --> 00:03:55,960 for your clients, and they must be able 81 00:03:57,059 --> 00:03:59,159 to specify which version they want to use.