AWS Serverless Application Model(SAM) provides short hand syntax to specify serverless resources such as lambda functions, API Gateway and dynamodb. The syntax can be used to model the application you want create in AWS using yaml.
AWS Lambda is a serverless, event-driven service that runs your code on demand.
- In this article we are going to develop a HTTP API locally with AWS SAM, deploy it to AWS and test the deployed API.
Table of Contents
- Create Lambda Function
- API Gateway
- HTTP API AWS SAM on VS Code
- Deploying to AWS
- Testing
- CloudWatch Logs
- Conclusion
Create Lambda Function.
- Search for Lambda on the search bar, on the left side bar click on Functions then on Create Function.
- Provide the needed details i.e Function name, runtime and architecture, then create function.
Use image for referral
API Gateway
- This is a fully managed service that makes it easy for developers to create, deploy, and manage APIs at any scale.
- On the page click on API so as to pick on the API you want to create.(We are building HTTP API)
Use image for reference
- Once you click on build:-
Step 1 - Add an Integration which will be Lambda, select the AWS and select the lambda function you created earlier. Provide an API name.
Step 2 - We shall Configure routes select a GET method and provide a resource path and the Intergration target is the lambda function we created.
Step 3 - Stages is the deployment environment where our API is going to be hosted. leave it to default and ensure that auto-deploy is activated, it comes in handy.
Step 4 - Review everything you have done and click on create if you are satisfied with it.
HTTP API AWS SAM on VS Code
Prerequisites
Ensure you have an AWS account.
Install AWS CLI using this link.
Configure your AWS using the
aws configurewhere you'll be needed to provide your AWS Key details.
In case you want to generate new ones use this link to generate new ones.Install the AWS SAM CLI using this documentation.
Install Docker here (Local Testing)
Install Nodejs here
Install AWS Toolkit VS Code Extension.
Install Thunder Client CLI extension on VS Code.
Create SAM project
- Create a folder and open it in VS Code.
Generate a default sam application using
sam init. Pick on AWS Quick Start application template. Hello world Example, nodejs14.x runtime and package type, zip package, Hello World Example starter template, N to x-ray tracing to avoid extra charges finally give your sam project a name.A folder with the sam project name will be generated, let's discuss it in details:-
events/: contains sample events that can be used for local testing of Lambda functions.hello-world/: contains an example AWS SAM app that is used to test that everything is working correctly..gitignore: used by git to determine which files and directories to ignore when committing changes to a repository.README.md: a markdown file that contains documentation for the project.samconfig.toml: a configuration file used by the SAM CLI to specify options and settings for deploying the application.template.yaml: defines the resources and configuration for the application.
Template.yaml Code Explanation
- Check out the full code in
template.yamlhere. Under the Resources section,HttpApidefines the resources that are going to be created on AWS. We've kept our default HelloWorldFunction that has a type of serverless function There are three events:
- GetUsers: Gets all the users from the API. Has type HttpApi, path of /user, method used is get, ApiId with a ref of HttpApi
Note
ApiId Ref(HttpApi) is defined above the HelloWorldFunction and has a type of serverless HttpApi with a stage name of nonprod(default)
GetUser:
Gets a single user by id from the the API.
Has type HttpApi, path of /user/{id}, method used is get, ApiId with a ref of HttpApiPostUser
Creates a new user.
Has type HttpApi, path of /user, method used is post, ApiId with a ref of HttpApi
app.js Code Explanation
- Check out the full code in
app.jshere. - This file defines the lambda handler i.e the code that will run when our lambda is invoked.
Responseis the object we get back from the lambda(API Response)const USERSis an array of objects that contain the users it has a property of name and userid.lambdaHandlerhas event and context passed in. In the event is where the http request will be injectedconsole.logthe event to get the http in cloudwatch logs.resultwill be passed in the response object. - First condition uses the event object passed in earlier and the routeKey(has the method used) Query parameters can be passed in for start and end(default for start is 0 and total array length for the end.) Validation
- first validation is to ensure the start is greater or equal to 0.
- second validation is to ensure the end is less or equal to the array length.
- third validation ensures the start is less than end.
- Second Condition we have the POST method and /user path where we will post new users to the user array
- Third Condition returns a single user using the method get and path of /user/{id} with a personalized greeting.
Deploying to AWS
Ensure you are in the directory that contains
template.yaml.Run
sam buildcommand to build the Lambda function and generate a deployment package.
aws-sam folder will be generated successfully.
N/B
Verify that your IAM user has the necessary permissions to perform the deployment. The required permissions are:
- AWSLambdaFullAccess
- IAMFullAccess
- AmazonAPIGatewayAdministrator
- AmazonS3FullAccess
- CloudFormationFullAccess
CloudWatchLogsFullAccess
Run
sam deploy --guidedfor step by step creation of CloudFormation stack using the SAM template and Lambda function code.
Provide a name for the app, use the default region, confirm the changes,allow IAM role creation, don't disable rollback, we do not have authorization so agree to it, we want our arguments saved in the configuration file and use default for the rest.
Confirm that we want to deploy the changes(it should be successful).On your AWS account under API Gateway you will see the just created HttpApi once you refresh it.
HttpAPi overview
- Under the routes section we can also see the paths we created as so:
All the routes have a configuration integration(same Lambda) as so:
Copy the stages copy the Invoke URL which we will use it for testing.
Testing
- We will use Thunder Client CLI extension for testing our API
GetUsers
We are doing a get request and the response will be all the users in our API.
To test the query string you can add the specifications at the end /user?start=1&end=3.
GetUser
This is also a get request with id specification the response is a personalized greeting with the user's name.
postUser
Using the post methos it adds a new user to the user array.
CloudWatch Logs
- Earlier we printed the events to the logs in CloudWatch.
- Once in cloudwatch go to log groups then find the correct log group then click on it.
- You will see an overview of it then at the bottom there is log streams which has all the calls made.
- The log has START, END and a REPORT like so:
Conclusion
AWS Serverless Application Model (SAM), AWS Lambda and Node.js make building APIs a breeze. With the steps outlined in this article, you can get started with your own simple API endpoint in no time. If you found this article helpful, be sure to connect with me and leave your comments and feedback. Happy coding!
Top comments (1)
Great