Serverless: Using AWS API Gateway to access DynamoDB
This story takes us through directly querying a DynamoDB table through the AWS API Gateway. In this story we will cover the high level of IAM polices, roles, user groups, and users that will be needed to use the API Gateway connecting to DynamoDB. We will also take you through setting up your first DynamoDB table, Creating API Gateway and then testing the API through Postman. As with many of the AWS stories there are lots of ways to accomplish the goal. We will be walking through one of the options.
Process Overview
Create DynamoDB Table -> Create IAM Policy, Role, User Group, User-> Create API Gateway -> Add Methods to the API Gateway -> Test the API with PostMan
Tools Used in this Story
- AWS DynamoDB
- AWS IAM
- AWS API Gateway
- Postman
Creating a DynamoDB Table
Navigate to the “DynamoDB” Service under AWS Services drop down and create a new table
Press the “Create table” button and then fill out the form with the table information. Note that we will be using the “String” option for your Primary key index on the DynamoDB table, we use a “String” option for the greatest flexibility in case we want to use a combo date/time.
Create an Item in DynamoDB
In order for us to be able to test the API Gateway in a later step we will want to create an item in the table.
Navigate to the “Item” tab after selecting the new DynamoDB table and press the “Create Item” button.
In this example we will use the “Text” format so it is readable JSON. Enter the JSON text and press “Save” button. This will create the first item in the DynamoDB table.
AWS IAM Setup
The next step in the process is to setup AWS IAM. In IAM we will need to create a policy, role, user group and user. The steps are below.
Create Policy
Define a new policy in AWS IAM, navigate to the Identity and Access Management (IAM) Service and navigate to “Access management” then Policies. Press the “Create Policy” Button
Press the “JSON” tab. Create a new policy JSON giving the actions you would like to allow. In this case we use PutItem, GetItem, Query, DeleteItem, and Scan. In this example we will only be testing and setting up the Scan item, but in future articles we will leverage this setup so we will be adding all of the options here. Then we put in the Resource you are granting the action on. In this case we are using the DynamoDB table we just created in the previous step. We have blanked out the AWS Account ID, you would put yours in place there. You can also get the ARN from the previous DynamoDB screen. Press the “Next: Tags” button.
On the Add tags screen you can populate any tags you want for the policy. We usually add a description at the very least to be able to remember why this policy is in place. Press the “Next: Review” button.
Create a Name for your new policy. In this case we used “DynamoDBGolfTournamentPolicy”, then press the “Create policy” button.
Query your new policy as you will need the ARN for the policy. The ARN string will be in the following format. The ARN for the policy will be need for the creation of the role.
arn:aws:iam::<customerNumber>:policy/<policyName>
Create Role
The next step is to create a role and assign the policy to the role that we create.
We will use the left navigation to select the “Roles” menu option. Then select the “Create role” button
Next we will setup the role based on a use case. We will select the “AWS service” and then select the use case that is labeled “API Gateway”.
After the “use case” is selected the workflow will take us to the “Attached permissions policies” screen. Here AWS will show the policy needed to use the API Gateway. The previous policy we setup will be used when we edit this role. For now we will proceed with just the default permissions policy for API Gateway. This permissions policy is used to push cloud watch logs so that we can troubleshoot the API.
Next we will add any tags and press “Next: Review” in the bottom right corner.
Finally, we will give the role a Name and then press the “Create role” button.
After we create the role we need to edit the role and attach additional policies to the role. This can be done by typing the role name or part of the role name in the search field. Then click on the role name “golfTournamentAPIGatewayRole.
On the Summary screen for the Role, make sure to copy the “Role ARN” as you will need it in the Create API Section. Then select the “Attach policies” button.
In the search window we type part of the policy name we created. Then check the box next to the policy name you created in the first step and press the attach policy button on the bottom of the screen
Create User
In order to secure our API we will need to have a programmatic access to AWS to access the API. The programmatic access will be used when we test the API with postman. Find and press the “users” on the left menu. We will populate the “User name” field and then select the “Access type” of “Programmatic access” on the “Add user screen”. Then press the “Permissions” button.
After we create the user, we will need to create a user group. Populate the “Group name” and then select the “Policy name” that we created in the earlier step. In our example we created a policy “DynamoDBGolfTournamentPolicy”. Then press the “Create group” button.
Then we will select the new created group and press the “Next: Tags” button.
In this example we are not going to add any tags but we could at this step. Then press the “Next: Review” button.
Next, we will review the user setup and create the user by pushing the “Create user” button.
Then we will save the Access Key, and Secret key displayed for the user to test with postman in a later step. Don’t forget to download the CSV so you do not need to generate the key again, which you can always do if you forget this step.
AWS API Gateway
Navigate to the Services list in AWS and select “AWS API Gateway”. Then press the button “Create API”
Next, we will select the type of API we are creating. In this example we will use “REST API”. Please note there are two different REST API. Selected the one labeled “Develop a REST API where you gain complete control over the request and response along with API management capabilities”
Populate the “API name”, “Description”, and select “Endpoint Type” of Regional. Then press the “Create API” button.
We will now have an API too configure to perform the operation we would like in DynamoDB. In this example we walk through a query (or scan) method so we are able to read data from the DynamoDB table.
Create Method
We will start by creating a new method, in this case we will create a “GET” method.
Press the “Actions” dropdown in the center column, and then select “Create Method”
Then on the screen you will see an empty box that has a dropdown on it. Select the dropdown and choose “GET” and then press the checkmark
We will now go through configuration of the “GET” method. Select the Integration type of “AWS Service”, select the region you created the DynamoDB table in. Select the AWS Service of “DynamoDB”, and populate the Action type of “Scan” and the execution role from the previous of Creating a role. Then press the save button.
After the save button is pressed AWS will take you to the GET — Method Execution overview screen. We will be navigating back and forth to this page quite a bit so get yourself familiar with it.
Integration Request
We will start with the Integration Request. Click the name inside the box “Integration Request”. This will take you to the following screen. Scroll to the bottom of the screen and select “Mapping Templates”. Then press the button “Add mapping template”. Then populate the field with application/json and click the small checkbox to the right.
If you left the first request body passthrough you may receive the following message. This will switch the option to “When there are no templates defined”
Then, we will populate a new template. In this case we are executing a scan against the “golfTournament” DynamoDB table. Then, press the “Save” button on the bottom right and navigate back to the Method Execution by pressing the text “Method Execution in the top middle of the screen.
Enable Cors
On the top middle of the screen press the “Actions” dropdown and select “Enable CORS”
This will take us to the screen to enable CORS. Press the “Enable CORS and replace existing CORS headers” button.
Next we will need to confirm the method changes. These are need to call the method from React.
Press the “Yes, replace existing values” button
Deploy the API
Navigate to the top middle of the screen and select the “Actions” dropdown and Select “Deploy API”
On the Deploy API Screen populate the “Deployment stage” as “[New Stage]”. The create a new “Stage name” and populate the optional fields “Stage description” and “Deployment description”, then press the “Deploy” button.
Depending on your naming convention of the stage you will come to a new screen and will be given the invoke URL. This will have the url to access your API Gateway. You will use this URL for the testing of the API with Postman.
Test the API using Postman
For this example we will walk through how to use Postman to test the API. We will start with creating a collection in Postman and storing the Auth Keys for AWS user in the collection.
Create a new collection
Open Postman and create a new collection by clicking the “Collections” logo on the left and then the “+” symbol next to it. Name your collection and click on the “Authorization” in the right tab.
Then we select the dropdown “AWS Signature”
From here we will populate the “AccessKey”, “SecretKey” and also populate the “AWS Region”
Then, we will click the “add request” link under our newly defined collection. We will populate the “GET” field with our Invoking URL that we received from the API Gateway step. On this screen if we were passing parameters to the API we would populate this in the Params fields but in this example we are doing a full query against the table.
Press the “Send” button and you should receive back any data that exists in the table in the response column on the right.
Hope you enjoyed this article, please post questions or comments if you run into issues and I’ll try to address them in a timely manner.
Thanks, Jason DeLano
