Creating Parameterised CloudFormation Stacks

Stages #

In the stack template, you configured events for the /hello-world path. But the actual path in the API is slightly different, and it includes the /Prod/ prefix. This is because SAM automatically creates a Prod stage for the implicit API.

In API Gateway terminology, a stage is a published version of the API configuration. Using stages allows API Gateway to serve a stable version of the API while users are adding or configuring resources to prepare for a new version. In the context of API Gateway, stages serve a very similar purpose to aliases of Lambda functions. You can even set up a ‘canary’ deployment where one version of the API gets just a percentage of traffic for a deployed stage.

An API needs at least one stage so that it becomes publicly accessible. In theory, you can set up different stages for development, testing, or production with a single API, but with SAM that’s not convenient. It’s a lot more common to create completely different stacks for different pipeline steps. The APIs you create using SAM will usually have a single stage.

Prod #

The standard stage name, Prod, forces users to remember a mix of upper-case and lower-case letters. Mixed-case URLs are a lot more error-prone than if everything is only lower case, so they are not advised. SAM lets you configure the stage name for an API, but you can’t set this through the Globals section. You’ll have to create an API explicitly and configure it.

CloudFormation API or SAM API? #

CloudFormation has two resources for managing Rest APIs, AWS::ApiGateway::RestApi and AWS::ApiGatewayV2::Api. SAM provides a convenient wrapper around lower-level resources with AWS::Serverless::Api. When you use the SAM wrapper, you don’t need to set up security policies for Lambda event mappings and worry about connecting to the ...