What is the difference between AWS and AWS_PROXY in CloudFormation::APIGateway?

Question

What is the difference between AWS and AWS_PROXY in a CloudFormation template with a AWS::ApiGateway::Method - Integration:Type, with a Lambda backend? I was constantly getting 502 errors just now and realized that I needed to respond with a very specifically formatted JSON response. When I created API Gateways from the console I never bumped into this issue. It does work now but I want to know the underlying differences so I can learn.

Here's the part from the CF Template:

VisitorCounterAPIGatewayRootMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      AuthorizationType: NONE
      HttpMethod: GET
      Integration:
        IntegrationHttpMethod: POST
        Type: AWS_PROXY #THIS is my question. AWS or AWS_PROXY?
        Uri: !Sub
          - arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${lambdaArn}/invocations
          - lambdaArn: !GetAtt VisitorCountLambda.Arn
      ResourceId: !GetAtt VisitorCounterAPIGateway.RootResourceId
      RestApiId: !Ref VisitorCounterAPIGateway

And here's the response code from my Lambda function (Python3.7):

apiResponse = {
    "isBase64Encoded": False,
    "statusCode": 200,
    "body": json.dumps({
        "visitorCount": int(float(response["Attributes"]["amount"]))
    })
}

Thank you.

Answer 1

AWS and AWS_PROXY are two types of integration in API Gateway.

• AWS_PROXY is only used with lambda and it is the simplest way of working with lambda with API Gateway. It means:

For HTTP proxy integration, API Gateway passes the entire request and response between the frontend and an HTTP backend. For Lambda proxy integration, API Gateway sends the entire request as input to a backend Lambda function. API Gateway then transforms the Lambda function output to a frontend HTTP response.

• AWS can be used with any AWS service, including lambda. It is more complex to setup and usually it is used when you want to integrate API gateway with, e.g., SQS or Kinesis or other AWS services:

This type of integration lets an API expose AWS service actions. In AWS integration, you must configure both the integration request and integration response and set up necessary data mappings from the method request to the integration request, and from the integration response to the method response.

So to answer your question:

Type: AWS_PROXY #THIS is my question. AWS or AWS_PROXY?

If you can, use AWS_PROXY. This is the most streamlined and easiest to work and setup form of integration with lambda. It only works with lambda anyway. Since entire response and reply are just pass-through the API gateway, you must ensure that your lambda returns correct headers and status code to the caller.

Use AWS with other services, such as SQS. You can still use lambda, but it requires more setup. But the benefit is that you have more control over what's get passed into your lambda, and how the response is passed to the caller. Usually you would use AWS with lambda if you have existing lambda and you can't change it. This way in AWS integration you can shape and mold the inputs and outputs from the caller to lambda and back, without changing the lambda.

Short example on AWS and AWS_PROXY integrations in CloudFormation, showing that when you use AWS integration, you can define extra parameters (myParam) that can be passed to your lambda:

AWS_PROXY

MyApiResourceMethod:
  Type: AWS::ApiGateway::Method
  Properties: 
    AuthorizationType: None
    HttpMethod: GET
    Integration: 
      IntegrationHttpMethod: POST 
      Type: AWS_PROXY
      Uri: !Sub >-
        arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${LambdaArn1}/invocations
    MethodResponses: 
      - ResponseModels: {"application/json": "Empty"}
        StatusCode: 200          
ResourceId: !Ref MyResource
RestApiId: !Ref MyRestApi 

AWS

MyApiResourceMethod:
  Type: AWS::ApiGateway::Method
  Properties: 
    AuthorizationType: None
    #AuthorizerId: String
    HttpMethod: GET
    Integration: 
      IntegrationHttpMethod: POST 
        - ResponseTemplates: 
            application/json: ""
          StatusCode: 200
      PassthroughBehavior: WHEN_NO_TEMPLATES
      RequestTemplates: 
        application/json: |
              {
                 "myParam": "$input.params('myParam')" 
              }            
      Type: AWS
      Uri: !Sub >-
        arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${LambdaArn2}/invocations
    MethodResponses: 
      - ResponseModels: {"application/json": "Empty"}
        StatusCode: 200          
    ResourceId: !Ref MyResource
    RestApiId: !Ref MyRestApi