1 00:00:00,180 --> 00:00:02,280 ‫So we have deployed our first API 2 00:00:02,280 --> 00:00:05,340 ‫through the API Gateway in a deployment stage. 3 00:00:05,340 --> 00:00:06,690 ‫So what we've seen is that 4 00:00:06,690 --> 00:00:09,600 ‫whenever we made changes to the API Gateway, 5 00:00:09,600 --> 00:00:12,360 ‫they were not effective until we did a deployment. 6 00:00:12,360 --> 00:00:15,660 ‫So we need to make a deployment for them to be in effect. 7 00:00:15,660 --> 00:00:17,790 ‫And it's a common source of confusion. 8 00:00:17,790 --> 00:00:19,920 ‫Some people will go and change how the API works, 9 00:00:19,920 --> 00:00:21,870 ‫but forget to do a deployment 10 00:00:21,870 --> 00:00:24,570 ‫and therefore the API will not be live. 11 00:00:24,570 --> 00:00:27,510 ‫So these changes are deployed to stages 12 00:00:27,510 --> 00:00:29,460 ‫and you can have as many stages as you want 13 00:00:29,460 --> 00:00:30,660 ‫and you can use the naming you want. 14 00:00:30,660 --> 00:00:34,020 ‫For example, you can use a dev, test, and prod stage 15 00:00:34,020 --> 00:00:36,870 ‫or a v1, v2, v3 whatever you want to do. 16 00:00:36,870 --> 00:00:40,170 ‫And each stage will get its own configuration parameters 17 00:00:40,170 --> 00:00:41,700 ‫and they can be rolled back seamlessly 18 00:00:41,700 --> 00:00:43,830 ‫because a whole history of all the deployments 19 00:00:43,830 --> 00:00:46,770 ‫that have happened onto a stage is kept. 20 00:00:46,770 --> 00:00:49,980 ‫So let's take the example of we have two stages 21 00:00:49,980 --> 00:00:51,930 ‫and we're creating a breaking API change. 22 00:00:51,930 --> 00:00:54,990 ‫So our Lambda function backing our API Gateway 23 00:00:54,990 --> 00:00:56,070 ‫is going to change. 24 00:00:56,070 --> 00:00:57,330 ‫So we have the v1 stage 25 00:00:57,330 --> 00:01:00,330 ‫and it invokes the v1 function and we've deployed it 26 00:01:00,330 --> 00:01:02,430 ‫and so our v1 clients are going to be able 27 00:01:02,430 --> 00:01:05,370 ‫to access our API through this URL. 28 00:01:05,370 --> 00:01:07,140 ‫But we are programming a new version 29 00:01:07,140 --> 00:01:09,630 ‫of our Lambda function called v2. 30 00:01:09,630 --> 00:01:11,700 ‫And this v2 does not respect the same format 31 00:01:11,700 --> 00:01:13,830 ‫of data and so on and so we know 32 00:01:13,830 --> 00:01:15,240 ‫that if we deploy the changes 33 00:01:15,240 --> 00:01:18,600 ‫on the v1 stage, it will break our v1 clients. 34 00:01:18,600 --> 00:01:20,700 ‫So what we do is then instead we decide 35 00:01:20,700 --> 00:01:23,670 ‫to create a new stage, call it the v2 stage, 36 00:01:23,670 --> 00:01:25,740 ‫pointing to the v2 function. 37 00:01:25,740 --> 00:01:28,320 ‫And this will create a new URL. 38 00:01:28,320 --> 00:01:31,320 ‫So now the api.example.com/v2, 39 00:01:31,320 --> 00:01:33,000 ‫which represents the v2 stage. 40 00:01:33,000 --> 00:01:35,400 ‫And the cool thing is that our clients 41 00:01:35,400 --> 00:01:37,920 ‫can now be updated to version two 42 00:01:37,920 --> 00:01:42,720 ‫and access this new URL, and we can maintain compatibility. 43 00:01:42,720 --> 00:01:45,540 ‫So for a while, the v1 and the v2 can coexist together 44 00:01:45,540 --> 00:01:46,950 ‫as two different stages. 45 00:01:46,950 --> 00:01:48,330 ‫We can migrate the clients 46 00:01:48,330 --> 00:01:50,250 ‫from the version one to the version two 47 00:01:50,250 --> 00:01:53,220 ‫and then when no more clients are using the version one, 48 00:01:53,220 --> 00:01:56,370 ‫then we can shut it down and move on with our API Gateway. 49 00:01:56,370 --> 00:01:59,940 ‫So this is a very common use cases for stages. 50 00:01:59,940 --> 00:02:01,800 ‫Now, how do we expand this? 51 00:02:01,800 --> 00:02:03,840 ‫We can use stage variables. 52 00:02:03,840 --> 00:02:06,930 ‫So stage variables are just like environment variables, 53 00:02:06,930 --> 00:02:09,510 ‫but for the API Gateway stages. 54 00:02:09,510 --> 00:02:12,510 ‫And you use them to change configuration values 55 00:02:12,510 --> 00:02:14,550 ‫without redeploying your API. 56 00:02:14,550 --> 00:02:16,320 ‫So they can be used, for example, 57 00:02:16,320 --> 00:02:18,060 ‫in the Lambda function ARN, 58 00:02:18,060 --> 00:02:21,270 ‫for the HTTP endpoint, for your parameter mapping templates. 59 00:02:21,270 --> 00:02:23,070 ‫And so you can change pretty much anything 60 00:02:23,070 --> 00:02:24,540 ‫through stage variables. 61 00:02:24,540 --> 00:02:27,450 ‫The use cases is to automatically configure 62 00:02:27,450 --> 00:02:29,370 ‫the HTTP endpoint your stages talk to. 63 00:02:29,370 --> 00:02:31,440 ‫Would it be dev, test, and prod, 64 00:02:31,440 --> 00:02:33,690 ‫or to pass configuration parameters to Lambda function 65 00:02:33,690 --> 00:02:35,070 ‫through mapping templates 66 00:02:35,070 --> 00:02:36,660 ‫or to point to the right Lambda function, 67 00:02:36,660 --> 00:02:38,280 ‫as we'll see in a second. 68 00:02:38,280 --> 00:02:39,960 ‫And so these stage variables will be passed 69 00:02:39,960 --> 00:02:42,390 ‫to the contact object in your Lambda function 70 00:02:42,390 --> 00:02:44,550 ‫so we can log it and get access to the value 71 00:02:44,550 --> 00:02:47,790 ‫of the stage variables directly from our Lambda functions. 72 00:02:47,790 --> 00:02:50,670 ‫Now, the format to access the value of a stage variable 73 00:02:50,670 --> 00:02:54,907 ‫within API Gateway is $stageVariables with an S 74 00:02:54,907 --> 00:02:56,880 ‫.variableName. 75 00:02:56,880 --> 00:02:59,940 ‫So here is a very, very common use cases 76 00:02:59,940 --> 00:03:02,160 ‫for your stage variables. 77 00:03:02,160 --> 00:03:04,830 ‫So we are going to create a stage variable 78 00:03:04,830 --> 00:03:07,440 ‫that will indicate the corresponding Lambda alias 79 00:03:07,440 --> 00:03:09,780 ‫that our API Gateway should invoke. 80 00:03:09,780 --> 00:03:11,910 ‫And so automatically the API Gateway will invoke 81 00:03:11,910 --> 00:03:13,320 ‫the right Lambda function. 82 00:03:13,320 --> 00:03:14,220 ‫So here is an example. 83 00:03:14,220 --> 00:03:17,850 ‫We have the dev stage pointing to the dev alias 84 00:03:17,850 --> 00:03:20,610 ‫and the dev alias is itself pointing 100% 85 00:03:20,610 --> 00:03:23,610 ‫of the traffic to the latest Lambda version. 86 00:03:23,610 --> 00:03:25,020 ‫We have a test stage pointing 87 00:03:25,020 --> 00:03:27,600 ‫to the test alias of Lambda function pointing 88 00:03:27,600 --> 00:03:29,670 ‫to the v2 version of our Lambda function. 89 00:03:29,670 --> 00:03:33,270 ‫And finally, the prod alias is linked 90 00:03:33,270 --> 00:03:36,030 ‫to the prod stage and pointing as well, 91 00:03:36,030 --> 00:03:40,620 ‫but this time, 95% on the v1 and 5% on the v2. 92 00:03:40,620 --> 00:03:43,140 ‫So in this case we can do a Lambda alias change 93 00:03:43,140 --> 00:03:45,420 ‫in the backend by updating the percentage 94 00:03:45,420 --> 00:03:46,710 ‫on different versions, 95 00:03:46,710 --> 00:03:49,050 ‫but we don't need to update the API Gateway. 96 00:03:49,050 --> 00:03:51,510 ‫Each stage points to the right alias 97 00:03:51,510 --> 00:03:53,070 ‫and each alias will be redirecting 98 00:03:53,070 --> 00:03:54,390 ‫to the right Lambda function. 99 00:03:54,390 --> 00:03:56,760 ‫So this is a very common pattern for the API Gateway 100 00:03:56,760 --> 00:03:59,370 ‫and one we'll be re-practicing in the next lecture. 101 00:03:59,370 --> 00:04:00,920 ‫So see you in the next lecture.