AWS Lambda is a paradigm shift for constructing our web applications. Lambda enables us to run code without having to run and maintain a server. Unfortunately, paradigm shifts are always difficult to adapt to. Going through real examples helps tremendously with learning Lambda. This short blog will bring up a Hello World Lambda. We will also show a small bit of configuration in API Gateway.
Amazon defines Lambda as "a serverless compute service that runs your code in response to events" https://aws.amazon.com/lambda/details/. Lambda can be used to respond to conditions that happen, like an object being updated in S3. One of the simplest use cases for Lambda is to respond to a web request. For a web request, the "event" is the http request. A Lambda function can not be hit directly from the web. Another AWS service must sit in front of Lambda and forward the request to the Lambda function. This service is called the API Gateway (https://aws.amazon.com/api-gateway/).
To understand our first Lambda Hello World example, we have to understand the minimum set up required. We need to set up API Gateway to accept requests at a certain URL. We configure API Gateway to hand the request off to AWS Lambda when it receives the request. The Lambda function will run and return results. These results will then be returned to the original caller.
First, we should build and load our Lambda code. I have created a simple github repo with a Java based Lambda example. This example is based on the code by Hakan Dilek found at his blog post. You must have Git, Gradle, and the JDK installed in order to complete these steps.
git clone git@github.com:holdorph/hellolambda.git
cd hellolambda
gradle shadowJar
The result of these commands will be a hellolambda-all.jar file in the hellolambda/build/libs/ directory. We will need to upload this file to Amazon when we configure our Lambda function. And this is the next step: Go to the Amazon AWS console and find the Lambda service. If you've never used Lambda your console might look like this.
Go ahead and click the blue "Get Started Now" button. If you are using an AWS account that already has some Lambda functions defined, you can simply press the blue "Create a Lambda function" button instead.
Amazon provides some blueprints that have a portion of the code already written. However, these blueprints are only in nodejs and python. In order to use our Java based Lambda function we will need to start from the "Blank Function." Click anywhere in the light-blue "Blank Function" box to be taken to the next page. This page allows you to define the event that causes your "Lambda Function" to run. We will eventually be defining an API Gateway request to be the trigger, but we have not yet created our API Gateway, so we currently have no trigger. Therefore, we can simply move to the next screen.
The "Configure function" screen is where most of the Lambda configuration will be done. The key parts on this configuration screen is to change the "Runtime" to "Java 8," upload your "hellolambda-all.jar" from earlier using the "Upload" button next to the "Function package" label, and finally you must specify the Java package/class name that is the entry point to your Handler. For the hellolambda example our Handler class is "example.Hello." Fill in the remaining required fields, including the Role and policy, then move to the "Next" screen.
Review your Lambda configuration. If everything looks correct then click the final "Create Function" button.
This will take a few moments, and then take you to a page where you can test your new Lambda function.
Now we can Click the blue "Test" button. The first time you test a Lambda function you have to fill in your test data. On subsequent tests, the same test data will be sent. If we test our function with an empty JSON body, we will see an empty response like this:
Now to change the test data we have to go up to the "Actions" menu and choose "Configure test event." This time we can enter a JSON body with a field "input" and a value of "Cris." Now when we click the "Save and test" button we should see "hello": "Cris" in the result section of the page.
Now our function is ready to be connected to a web request using API Gateway. We will not get into configuring API Gateway in depth.
The following instructions provide you with very quick access to your Lambda function. To begin, select the "API Gateway" option from your Amazon console. Similar to Lambda, if this is your first time configuring API Gateway, you can press the blue "Get Started" button. If your account already has API Gateway configured you can instead press the blue "Create API" button. Select "New API," enter in a name for the "API name" field, and then press the blue "Create API" button.
Now that the API is created, we must create set up a URL path and which HTTP methods the path will respond to. To do this find the "Actions" drop down and select "Create Method."
Under the "/" a new dropdown appears, select this dropdown and choose "ANY," then click the checkmark.
This brings you to a new setup screen. You should already have "Lambda Function" checked for "Integration type." Choose the "Lambda Region" where your Lambda function was created, then begin typing your function name in the "Lambda Function" text box. As soon as you begin typing, the available functions that match the characters you type should become available to select. Select your function name when you see it appear. Finally, press the blue "Save" button.
You will be prompted to confirm that you are about to give API Gateway permission to the Lambda Function. Review the function it lists and then press blue "OK" button if the function is the correct one.
You should then see a screen similar to this one.
To perform the last step in configuring the API Gateway, you must select the "/" path and then choose the "Deploy API" action from the "Actions" dropdown.
Select "[New Stage]" for the "Deployment stage" and fill in a Stage name, in this example we have used "test." Then press the blue "Deploy" button.
We now have a URL that will hit our Lambda function. Copy the URL from the light blue box and paste it into a new browser tab.
The output from putting the URL into a browser and hitting the enter key will be a response of "{}". This is because we have not sent any JSON to the Lambda function. To do that we would need to use another kind of tool that allows us to send a JSON body as part of the web request. There are many tools capable of doing this. One simple tool is the command line tool "curl."
In this example, we issued the command:
curl -H "Content-Type: application/json" -X POST -d '{"input":"Cris"}' https://g1iu8o140c.execute-api.us-west-2.amazonaws.com/test
And the server responds with:
{"hello":"Cris"}
We now have a fully functioning Lambda function written in Java, connected to an API Gateway and responding to web requests. From here, we can begin to build more complicated services and utilize API Gateway to manage access to those services.
