1 00:00:00,862 --> 00:00:03,791 -: Our next topic is versioning. 2 00:00:03,791 --> 00:00:07,170 Now, versioning is also a very important aspect 3 00:00:07,170 --> 00:00:12,170 of API design, as in often overlooked by API designers. 4 00:00:12,240 --> 00:00:13,636 So what is so important 5 00:00:13,636 --> 00:00:15,903 about versioning in API. 6 00:00:16,980 --> 00:00:18,420 When designing API, 7 00:00:18,420 --> 00:00:20,970 one of the assumption you have to make is 8 00:00:20,970 --> 00:00:24,060 that your API will be updated over time. 9 00:00:24,060 --> 00:00:27,930 This update can include many things such as adding actions, 10 00:00:27,930 --> 00:00:32,220 removing actions, and of course changing actions such as 11 00:00:32,220 --> 00:00:34,951 adding parameters or removing parameters. 12 00:00:34,951 --> 00:00:37,530 Now, this is fine, but 13 00:00:37,530 --> 00:00:39,210 we always have to remember 14 00:00:39,210 --> 00:00:42,060 that we do not control our clients. 15 00:00:42,060 --> 00:00:44,910 The ones who are using the API 16 00:00:44,910 --> 00:00:46,470 we don't know who they will be. 17 00:00:46,470 --> 00:00:50,392 We don't know what tools and what clients they will use. 18 00:00:50,392 --> 00:00:54,810 We don't know what is their upgrade life cycle 19 00:00:54,810 --> 00:00:56,580 and we definitely 20 00:00:56,580 --> 00:00:58,680 cannot force the client to 21 00:00:58,680 --> 00:01:01,529 upgrade the version of their clients they are using. 22 00:01:01,529 --> 00:01:05,108 So if one of our clients develop the API client 23 00:01:05,108 --> 00:01:07,860 against a specific version of the API 24 00:01:07,860 --> 00:01:09,090 and the API 25 00:01:09,090 --> 00:01:10,140 is now 26 00:01:10,140 --> 00:01:14,610 modified then this specific client will stop working 27 00:01:14,610 --> 00:01:16,697 and we definitely don't want that to happen. 28 00:01:16,697 --> 00:01:20,850 We always want to make sure our clients can actually 29 00:01:20,850 --> 00:01:22,950 continue using our API. 30 00:01:22,950 --> 00:01:24,359 So what can be done? 31 00:01:24,359 --> 00:01:27,000 Well, there are two things that should be 32 00:01:27,000 --> 00:01:30,270 done regarding versioning in in the API. 33 00:01:30,270 --> 00:01:34,110 So the first one is to set a version support policy 34 00:01:34,110 --> 00:01:35,970 for each version of the API. 35 00:01:35,970 --> 00:01:39,634 We must clearly state what is the supported lifetime 36 00:01:39,634 --> 00:01:41,220 of this version. 37 00:01:41,220 --> 00:01:42,620 For example, take a look 38 00:01:42,620 --> 00:01:46,830 at this API end of life statement from Salesforce. 39 00:01:46,830 --> 00:01:49,680 As you can see, Salesforce clearly states 40 00:01:49,680 --> 00:01:52,110 that each API version is supported 41 00:01:52,110 --> 00:01:56,330 for a minimum of three years from the date of zero release. 42 00:01:56,330 --> 00:01:58,723 Now, this document doesn't mention what happens 43 00:01:58,723 --> 00:02:00,636 after the three years 44 00:02:00,636 --> 00:02:03,762 but clients must assume that after three years 45 00:02:03,762 --> 00:02:07,091 the version they are using will not be supported anymore. 46 00:02:07,091 --> 00:02:10,110 Now, having this document gives a peace 47 00:02:10,110 --> 00:02:11,760 of mind to the client. 48 00:02:11,760 --> 00:02:14,438 They know that when a new version is released 49 00:02:14,438 --> 00:02:17,580 then the version they're currently using will be supported 50 00:02:17,580 --> 00:02:19,560 for at least another three years 51 00:02:19,560 --> 00:02:21,150 and this will give them plenty 52 00:02:21,150 --> 00:02:23,520 of time to adapt to the new version. 53 00:02:23,520 --> 00:02:26,810 So setting a version support policy is the first 54 00:02:26,810 --> 00:02:30,478 thing that should be done regarding versioning. 55 00:02:30,478 --> 00:02:33,180 The second thing is to include the versioning 56 00:02:33,180 --> 00:02:35,348 in the API itself, 57 00:02:35,348 --> 00:02:39,483 and in the next lecture we will see exactly how to do it.