Looking for Senior AWS Serverless Architects & Engineers?Let's Talk
In this tutorial, we are going to see how to build a CRUD (Create, Read, Update, & Delete) API with node js using an SQL-compatible query language known as PartiQL to communicate with DynamoDB and AWS SAM as the framework. We are going to be looking at a simple case of an appointment crud API letting one create, update, view, and delete appointments from a DynamoDB table.
In order to properly follow through successfully with this tutorial, you’ll need to have the following:
- You need to have an AWS account with administrative access. If you don’t have an AWS account, kindly use the link to create a free trial account for AWS.
- An IDE (e.g. VS CODE)
- Set up AWS credentials in your IDE
- AWS toolkit for VS code
- AWS SAM CLI - Install the AWS SAM CLI
- Node.js - Install Node.js 18, including the npm package management tool
- Postman for testing the API
Create DynamoDB table
Log into the AWS Management Console
While on the console, select Services, next select Database, and then select DynamoDB
In the next screen that displays, click on Tables, then click on Create table
On the screen that follows, fill in the fields as seen below and click Create table
Now we have our DynamoDB table fully setup and can move to the creation of our project.
Create a new SAM application
Launch VS code and navigate to your project folder (e.g. Appointment)
Then Launch the terminal
In your terminal type ‘sam init’ and hit the enter/return key. You should have a similar output as shown below:
Insert ‘1‘ into the terminal and hit the enter/return key. Your output should be as follows:
Select any template of your choice by inserting the template number into the terminal, in this case, we will be selecting the first template ‘1’ as seen above.
You will be asked to use the most popular runtime and package as shown below, insert N and hit the enter/return key to continue.
In the list of presented environments as seen above, insert the number corresponding to nodejs14.x in our case that will be 14. Hit the enter/return key then you will be asked to insert the package type; insert 1 for zip, and hit the enter/return key. Your output should be similar to the following:
For the starter template, insert ‘1’ then hit the enter/return key. You will be asked a couple of questions as shown below simply enter N and hit the enter/return key for each question till you reach the project name.
For the project name, enter ‘Appointment’ and then hit the enter/return key. Your output should be as follows:
Now we have a sample SAM sample project ready for us to use.
Building the Appointment CRUD API
We are now going to restructure our sample app as follows:
- Delete everything inside the sample appointment folder EXCEPT the template.yaml file
- Create a new folder called Functions
- Create the following files insertAppointment.js, getAppointments.js, updateAppointment.js, deleteAppointment.js inside the Functions folder
Your output should look as follows:
Insert the following code in the insertAppointment.js file:
Insert the following code in the getAppointments.js file:
Insert the following code in the updateAppointment.js file:
Insert the following code in the deleteAppointment.js file:
Update the template.yaml file so it looks exactly as below:
Create a file in the root application called api.yaml. Your app structure should now look as follows:
Insert the following code in the api.yaml file you recently created:
Deploy to AWS
Now that we have everything ready, we will move over to the deployment phase.
Navigate to the project folder using the cd command and install the uui dependency that we used in the insertAppointment.js file using npm install as shown below:
Navigate to the Functions folder and create a package.json file as shown below, validating each field by hitting the return/enter key.
Update the newly created package.json as follows to include dependencies:
Navigate back to the root folder using the command cd
Build the app using sam build, your output should be similar to the one below:
Next, we use the command sam deploy —guided and follow the steps as seen below. You will be presented with a couple of questions; feel free to modify your response, then hit the enter/return key to proceed to the next question.
To finalize the deployment, insert y, then hit the enter/return key to proceed.
Your output should be as follows:
Verify resources in AWS
To verify our functions were created, go to the AWS console, click on services, then click on compute, and then click on Lambda.
You should be able to see the four functions we created as seen below:
To check the gateway, go to services in the AWS console, click on Networking & content delivery, then click on API Gateway.
You should find the created API as shown below:
Test your API
Now that we have it all in place, its time to see if our API works.
First, we retrieve the API URL. You can do this via the following methods:
Through the output you got after deployment on step 7 of Deploy to AWS
Go to your API Gateway as you did in step 2 to verify resources in AWS. Click on the Appointment API; select Stages, select Dev, and then select Get, Post, Delete, or Put, depending on which API you want to retrieve.
Note: All API URLs will be the same except for Delete and Put, which will require a parameter (id) when calling the API.
Launch postman and sign in. Click on the + symbol next to the overview tab to open a new tab.
To test the GET API, select GET from the dropdown menu, enter the get URL retrieved earlier then click Send.
You should see a similar screen to the one below once you are done. Notice we have an empty list of items (4) returned because our Appointment table is empty.
To test the POST API, select POST from the dropdown list, do not change the API URL, click on Body, select Raw and insert the following code:
Click Send to process the request. Your output should be as follows:
As seen in the image above (5) you will observe we have an auto-generated id, save the id as we will be needing it in the next step.
Repeat this step to insert multiple data or records into the Appointment DynamoDb.
To check the newly added record, repeat Step 3 and this time your output should be as follows:
You could also check the DynamoDB Table by going to the AWS console and then Services. Then click Databases, and then click on DynamoDB.
Click on Tables to the left, select the Appointment table to the right, then click on Actions, and then select Explore items.
Your output should be as seen below:
To test the PUT API, select PUT from the dropdown list, add the saved id in Step 4 to the API URL, click on Body, select Raw, and update the code (we will be updating the date) as seen below:
Click on Send to process the request. Your output should be as follows:
If you verify that the update was successful using Step 3 then your output should literally be as follows:
To test the DELETE API, select DELETE from the dropdown list, add the saved id in Step 4 to the API URL, and then click on Send to process the request. Your results should be as follows:
You can verify what you have with the results shown in Step 4; they should be exactly the same.
Now we got a fully working API to interact with our DynamoDB table using PartiQL, you could grab the complete code and try it out here.
In this tutorial, we looked at how to create and test a CRUD API using:
- The AWS Console
- VS code as our IDE
- SAM for Infrastructure as Code
- PartiQL and DynamoDB
- Postman for API testing