APi gateway proxy integration vs Lambda integration

Lambda Integration vs. Lambda Proxy Integration with AWS API Gateway

API gateway is the most popular and powerful way to open your Lambda to the world.

But there are two ways to integrate your Lambda with the API gateway.

Lambda Proxy Integration
Lambda Integration or Custom Integration

The difference between Lambda Proxy integration and Lambda Non-Proxy integration can be confusing.

In this post, we will see how to configure both of them using AWS CDK and what the differences are between them.

What is Lambda Proxy Integration?

This is the recommended way to create a connection between a Lambda function and API Gateway.

The request is passed to the lambda function as is.
The response from the lambda function is passed to the client as is.

The diagram can look like this,

client -> API Gateway (no transformation) -> Lambda Function

This is the main thing to understand. The API gateway doesn’t do any transformation or modification of the incoming request or the outgoing response.

This means it’s your (the lambda functions) job to send the response and the status code in the correct format.

And that specific format is

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "Hello World"
}

So your lambda function must return a response of this type. Also, you can send the error in the following format.

{
  "statusCode": 400,
  "body": "Something went wrong!"
}

So in a proxy integration, your lambda is in charge of everything. The API gateway doesn’t interfere with any of these.

Advantages of Proxy integration

This is easy to set up. So you can do rapid prototyping.
Easily control your status codes and custom headers.

Disadvantages of Proxy Integration

Generating documentation is hard.
Everything is inside code, so it’s tightly coupled with the API gateway.

What is Lambda Custom Integration?

In a non-proxy integration, you can set up the API gateway so that it does some transformation on the request and response.

client -> API Gateway (some transformation) -> Lambda Function

And this opens up a lot of opportunities. For example,

You can do a lot of transformations before passing the request to the lambda function. Maybe add some special header or extra information.
You can do a lot of transformations before passing the response back to the client. For example, you might hide some fields returned from the lambda function.

API gateway uses VTL (Velocity Template Language) to transform requests and responses.

Your lambda is not bound to return any specific response format in this type of integration.

Advantages of Lambda Custom integration

This is very powerful. You are in full control.
The lambda code is decoupled from the API gateway.
Documentation generation becomes very easy.

Disadvantages of Lambda Custom Integration

Very time-consuming to set up properly.
You need to know the VTL language.

Which One is Better?

AWS recommends using the Lambda Proxy integration for lambda functions. Also, this is the fastest way to do things and feels native.

So in most cases, you should use Lambda Proxy Integration.

However, if you have a powerful need to do otherwise, you can opt for Lambda Custom Integration. One such case might be the requirement to generate documentation.

Now let’s see how we can do both using AWS CDK.

AWS Proxy integration with AWS CDK

Below is a code snippet that connects a lambda function with an API gateway using proxy integration.

const lambdaFn = new NodeJSLambdaFunction() // any normal lambda function

const restAPI  = new RestApi() // any normal RestAPI

const proxyIntegration = new apigateway.LambdaIntegration(lambdaFn);

const resource = restAPI.root.addResource('any-route');

resource.addMethod("POST", proxyIntegration, {
    authorizer: authorizer, // optional authorizer
  }
);

AWS Lambda Integration using a custom integration

const lambdaFn = new NodeJSLambdaFunction() // any normal lambda function

const restAPI  = new RestApi() // any normal RestAPI

const proxyIntegration = new apigateway.LambdaIntegration(lambdaFn,{
    proxy: false, // this is to indicate that we want a custom integration
    passthroughBehavior: apigateway.PassthroughBehavior.WHEN_NO_MATCH,
    integrationResponses: [
      {
        statusCode: "200", // the simplest format. We can customize it.
      },
    ],
  }
);

const resource = restAPI.root.addResource('any-route');

resource.addMethod("POST", proxyIntegration, {
    authorizer: authorizer, // optional authorizer
    methodResponses: [
        {
          statusCode: "200", // Simplest format. Otherwise you will get error
          responseModels: {
            'application/json': apigateway.Model.EMPTY_MODEL,
          },
        },
    ],
  }
);

That’s it for today. Have a great day! the complete code can be found here