AWS::ApiGateway::Stage requires DeploymentId ... but where do I find this?

Question

I am trying to programmatically set up stages as part of my AWS API Gateway deployment. I am using SAM CLI. The cloudformation docs give the definition:

DeploymentId The ID of the deployment that the stage points to.

Required: Yes

Type: String

Update requires: No interruption

and the code example:

Resources:
  Prod:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: Prod
      Description: Prod Stage
      RestApiId: !Ref MyRestApi
      DeploymentId: !Ref TestDeployment ##      <===== this
      DocumentationVersion: !Ref MyDocumentationVersion
      ClientCertificateId: !Ref ClientCertificate
      Variables:
        Stack: Prod
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          MetricsEnabled: 'true'
          DataTraceEnabled: 'true'
        - ResourcePath: /stack
          HttpMethod: POST
          MetricsEnabled: 'true'
          DataTraceEnabled: 'true'
          ThrottlingBurstLimit: '999'
        - ResourcePath: /stack
          HttpMethod: GET
          MetricsEnabled: 'true'
          DataTraceEnabled: 'true'
          ThrottlingBurstLimit: '555'

..but no context as to what the value TestDeployment points to.

• Is it a random string the user selects?
• Is it a generated ID that is available somewhere?
• Is it the name of a Resource or API? etc.

I have been googling and still can't seem to get an answer.

Looking in the AWS management console, I can see looking at some of our already existing APIs - that when stages already exist (manually set up) you can get a deployment ID via the stages, but if I have to manually set them up first, that would kind of partially defeat the purpose of CloudFormation's AWS::ApiGateway::Stage wouldn't it (...ideally, we hope to be able to create API's completely via code, without going into the AWS interface)? And wouldn't the deploymentId only be available after the deployment? If it's available prior (as part of the build), how do I fetch it and get it into my cloudformation.yaml prior to a deploy?

Any help in understanding this is appreciated!

Answer 1

A Deployment contains metadata about an API Gateway deploy, such as a description, and can also be used to deploy a canary release. You can create a Deployment resource as part of your CloudFormation template.

Deployment: 
  Type: AWS::ApiGateway::Deployment
  Properties: 
    RestApiId: 
      Ref: "MyApi"
    Description: "My deployment"
    StageName: "DummyStage"

When you !Ref it it will return the DeploymentId. Make sure to read the section of the docs called AWS::ApiGateway::Method Dependency to learn how to attach API methods to the deployment.