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 right Lambda version or alias. To achieve the same result with lower-level resources, you would need a lot more template code.

You can use the reference to a SAM wrapper resource instead of lower-level resources in all the places where CloudFormation expects the identifier of a REST API. If SAM created an API implicitly, you can get its identifier using the automatically generated ServerlessRestApi reference.

Defining stack parameters #

Having /Prod/ in the URL might not feel right to you, but that’s a matter of taste. Whatever you choose as a nice URL, other people might not like. You can make a template that works for everybody by introducing a stack parameter. Parameters are a way to create customisable stacks. Users can set the parameter value to provide their own configuration when deploying a stack. This makes it easy to publish reusable stacks and even connect the outputs of one stack to the inputs of another.

Let’s first create a parameter to hold the stage name. Define a top-level section called Parameters in your template. For example, add it immediately after the Globals section. Set up a parameter by providing its name as a key then list the expected type and default value as in the following listing: