Deploy AWS API to Multiple Stages When AWS SAM Replaces Previous Stages

June 15, 2019  2 minute read  

Learn how to create multiple API Gateway deployment stages even though AWS SAM replaces previous stages in subsequent deployments.

Note that this is a workaround to AWS SAM template replaces previously deployed stage when you change API StageName property on yaml. It is probably not an optimal solution as it involves an extra step after deployment via CodePipeline.


Follow the following steps to adopt this workaround.

1. Specify Stage Name

In your yaml file, specify stage name that you want CodePipeline to deploy to. For example, set it as ‘Prod’ if you want it to deploy to Prod stage.

  Type: AWS::Serverless::Api
    StageName: Prod

2. Create Another Stage

Open AWS API Gateway console and select your API. Then, click Actions button to open up a menu and select Deploy API.

AWS API Gateway Console Integration Request

Specify your desired deployment stage name and description before deploying your API. Click Deploy to deploy your API.

AWS API Gateway Console Integration Request

3. New Stage

You have deployed your API to a new stage. The associated invoke url will contain the stage name you set in the previous step.

AWS API Gateway Console Integration Request

4. Future Deployment

For future deployments, after you deploy using CodePipeline, it will only deploy to the stage specified on your yaml file. It will not affect the stage you manually deployed on AWS API Gateway console.

4.1 AWS API Gateway Console

Thus, to deploy to your manually deployed stage, you have to go to API Gateway and repeat step 2.

4.2 AWS API Gateway CLI

You can also deploy your API using AWS API Gateway CLI create-deployment command.

aws apigateway create-deployment \
--rest-api-id YOUR_API_NAME --stage-name YOUR_STAGE_NAME

AWS API Gateway create-deployment CLI summary:

--rest-api-id <value>
[--stage-name <value>]
[--stage-description <value>]
[--description <value>]
[--cache-cluster-enabled | --no-cache-cluster-enabled]
[--cache-cluster-size <value>]
[--variables <value>]
[--canary-settings <value>]
[--tracing-enabled | --no-tracing-enabled]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]


With this setup, your future deployments via CodePipeline won’t affect the stages you define manually on AWS API Gateway console. However, to add new changes to these manually added stages, you have to go to AWS console or use API Gateway CLI to redeploy your API.

Good thing about this method is your deployment will not affect stages that you manually deploy.

Support Jun

Thank you for reading!    Support JunSupport Jun

Support Jun on Amazon US

Support Jun on Amazon Canada

If you are preparing for Software Engineer interviews, I suggest Elements of Programming Interviews in Java for algorithm practice. Good luck!

You can also support me by following me on Medium or Twitter.

Feel free to contact me if you have any questions.