Tutorial: Create a REST API with a Lambda proxy integration
Lambda proxy integration is a lightweight, flexible API Gateway API integration type that allows you to integrate an API method – or an entire API – with a Lambda function. The Lambda function can be written in any language that Lambda supports. Because it's a proxy integration, you can change the Lambda function implementation at any time without needing to redeploy your API.
In this tutorial, you do the following:
-
Create a "Hello, World!" Lambda function to be the backend for the API.
-
Create and test a "Hello, World!" API with Lambda proxy integration.
Create a "Hello, World!" Lambda function
To create a "Hello, World!" Lambda function in the Lambda console
Sign in to the Lambda console at https://console.aws.amazon.com/lambda
. -
On the AWS navigation bar, choose an AWS Region.
Note
Note the region where you create the Lambda function. You'll need it when you create the API.
-
Choose Functions in the navigation pane.
-
Choose Create function.
-
Choose Author from scratch.
-
Under Basic information, do the following:
-
In Function name, enter
GetStartedLambdaProxyIntegration
. -
For Runtime, choose either the latest supported Node.js or Python runtime.
For Architecture, keep the default setting.
-
Under Permissions, expand Change default execution role. For Execution role dropdown list, choose Create new role from AWS policy templates.
-
In Role name, enter
GetStartedLambdaBasicExecutionRole
. -
Leave the Policy templates field blank.
-
Choose Create function.
-
-
Under Function code, in the inline code editor, copy/paste the following code:
-
Choose Deploy.
Create a "Hello, World!" API
Now create an API for your "Hello, World!" Lambda function by using the API Gateway console.
To create a "Hello, World!" API
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
If this is your first time using API Gateway, you see a page that introduces you to the features of the service. Under REST API, choose Build. When the Create Example API popup appears, choose OK.
If this is not your first time using API Gateway, choose Create API. Under REST API, choose Build.
For API name, enter
LambdaProxyAPI
.(Optional) For Description, enter a description.
Keep API endpoint type set to Regional.
Choose Create API.
After you create an API, you create a resource. Typically, API resources are organized in a resource tree according to the application logic. For this example, you create a /helloworld resource.
To create a resource
Choose Create resource.
Keep Proxy resource turned off.
Keep Resource path as
/
.For Resource name, enter
helloworld
.Keep CORS (Cross Origin Resource Sharing) turned off.
Choose Create resource.
In a proxy integration, the entire request is sent to the backend Lambda
function as-is, via a catch-all ANY
method that represents any HTTP
method. The actual HTTP method is specified by the client at run time. The
ANY
method allows you to use a single API method setup for all
of the supported HTTP methods: DELETE
, GET
,
HEAD
, OPTIONS
, PATCH
,
POST
, and PUT
.
To create an ANY
method
Select the /helloworld resource, and then choose Create method.
For Method type, select ANY.
For Integration type, select Lambda function.
Turn on Lambda proxy integration.
For Lambda function, select the AWS Region where you created your Lambda function, and then enter the function name.
-
To use the default timeout value of 29 seconds, keep Default timeout turned on. To set a custom timeout, choose Default timeout and enter a timeout value between
50
and29000
milliseconds. Choose Create method.
Deploy and test the API
To deploy your API
Choose Deploy API.
For Stage, select New stage.
For Stage name, enter
test
.(Optional) For Description, enter a description.
Choose Deploy.
Under Stage details, choose the copy icon to copy your API's invoke URL.
Use browser and cURL to test an API with Lambda proxy integration
You can use a browser or cURL
To test GET
requests using only query string parameters, you can enter the URL for the API's
helloworld
resource into a browser address bar.
To create the URL for the API's helloworld
resource, append the resource helloworld
and the query string parameter ?greeter=John
to your invoke URL. Your URL should look like the following.
https://
r275xc9bmd
.execute-api.us-east-1
.amazonaws.com/test/helloworld?greeter=John
For other methods, you must use more advanced REST API testing utilities, such as
POSTMAN
To test your deployed API using cURL:
-
Open a terminal window.
-
Copy the following cURL command and paste it into the terminal window, and replace the invoke URL with the one you copied in the previous step and add
/helloworld
to the end of the URL.Note
If you're running the command on Windows, use this syntax instead:
curl -v -X POST "https://
r275xc9bmd
.execute-api.us-east-1
.amazonaws.com/test/helloworld" -H "content-type: application/json" -d "{ \"greeter\": \"John\" }"To call the API with the query string parameter of
?greeter=John
:curl -X GET 'https://
r275xc9bmd
.execute-api.us-east-1
.amazonaws.com/test/helloworld?greeter=John'To call the API with a header parameter of
greeter:John
:curl -X GET https://
r275xc9bmd
.execute-api.us-east-1
.amazonaws.com/test/helloworld \ -H 'content-type: application/json' \ -H 'greeter: John'To call the API with a body of
{"greeter":"John"}
:curl -X POST https://
r275xc9bmd
.execute-api.us-east-1
.amazonaws.com/test/helloworld \ -H 'content-type: application/json' \ -d '{ "greeter": "John" }'
In all the cases, the output is a 200 response with the following response body:
Hello, John!