AWS SAM template - set Integration response mapping template

Question

I have a AWS SAM template that creates a API Gateway hooked into a Step Function.

This is all working fine, but I need to add a Integration Response Mapping Template to the response back from Step Functions.

I cant see that this is possible with SAM templates?

I found the relevant Cloud Formation template for it: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apitgateway-method-integration-integrationresponse.html

But It looks like I would have to create the whole AWS::ApiGateway::Method / Integration / IntegrationResponses chain - and then I'm not sure how you reference that from the other parts of the SAM template.

I read that it can be done with openAPI / Swagger definition - is that the only way? Or is there a cleaner way to simply add this template?

This is watered down version of what I have just to demonstrate ...

Transform: AWS::Serverless-2016-10-31
Description: My SAM Template
Resources: 

  MyAPIGateway:
    Type: AWS::Serverless::Api
    Properties:
      Name: my-api
      StageName: beta
      Auth:
        ApiKeyRequired: true 
        UsagePlan: 
          CreateUsagePlan: PER_API
          UsagePlanName: my-usage-plan
          Quota:
            Limit: 1000
            Period: DAY
          Throttle:
            BurstLimit: 1000
            RateLimit: 1000
      
  MyStateMachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      Name: my-state-machine
      DefinitionUri: statemachines/my-state-machine.asl.json
      Events:
        MyEvent:
          Type: Api
          Properties:
            Path: /myApiMethod
            Method: post
            RestApiId: !Ref MyAPIGateway

          # TODO: how to we define this Integration Response Template ?
          # IntegrationResponse:
          #   Template:
          #     application/json: |
          #         ## parse arn:aws:states:REGION:ACCOUNT:execution:STATE_MACHINE:EXECUTION_NAME
          #         ## to get just the name at the end
          #         #set($executionArn = $input.json('$.executionArn'))
          #         #set($arnTokens = $executionArn.split(':'))
          #         #set($lastIndex = $arnTokens.size() - 1)
          #         #set($executionId = $arnTokens[$lastIndex].replace('"',''))
          #         {
          #           "execution_id" : "$executionId",
          #           "request_id" : "$context.requestId",
          #           "request_start_time" : "$context.requestTimeEpoch"
          #         }
  
    

Answer 1

Right now you're using AWS SAM events in your state machine to construct the API for you, which is a very easy way to easily construct the API. However, certain aspects of the API cannot be constructed this way.

You can still use AWS SAM however to construct the API with all the advanced features when you use the DefinitionBody attribute of the AWS::Serverless::Api (or the DefinitionUri). This allows you to specify the API using the OpenAPI specification with the OpenAPI extensions.

You still need to define the event in the StateMachine though, since this will also ensure that the correct permissions are configured for your API to call your other services. If you don't specify the event, you'll have to fix the permissions yourself.