Part 3: Adding API Gateway and the Article Page

In this post we will add API Gateway to our CloudFormation template and add the article page endpoint to API Gateway using OpenAPI.  We will demo that new endpoint being used to display the sample article we added directly to the DynamoDB table in the previous post.

This post picks up where we left off in Part 2: Planning the Data Model.  If you did not go through that post, you can get the project files we will be using as our starting point here.

First we need to create an IAM role for our API Gateway to use.  This role will give API Gateway the permissions it needs to read the data from our DynamoDB Table.  We will then create our API Gateway and add an output to our CloudFormation template.  That output we are adding will return the URL to our new endpoint.  To add these CloudFormation resources, add the following to your template.yaml file.

In the API Gateway definition above, you will notice that it is very brief and it references another file openapi.yaml.  That is the OpenAPI definition file and almost all of the API definition occurs in that file.  Create a new file in your project named openapi.yaml with the content below:

Let's walk through what is going on in this openapi.yaml file.  The important part of this file is the paths section.  Right now we are defining only one path, but it is a very powerful path definition, using what is called a greedy path parameter.  The path specification of /{path+} defines that any request that is more than just the root of the API Gateway endpoint will be accepted by this route.  Also everything in the URL after the API Gateway's root will be available to us as a parameter named path.  On the next line we specify the only HTTP verb that we are configuring for that path at this time, the GET HTTP verb.

Now for the section x-amazon-apigateway-integration this is where all of the magic happens with API Gateway and it proxying DynamoDB for us.  The highlights are:

1. credentials - this references the IAM role that we created in template.yaml which gives our API Gateway permissions to access our DynamoDB table.
2. uri - this is where we specify what action we want this endpoint to execute on our DynamoDB table, we want to Query a DynamoDB table in us-east-1 so our uri is 'arn:aws:apigateway:us-east-1:dynamodb:action/Query'
3. responseTemplates - this is where we define exactly how we want the response to be presented to the requestor.  We have Velocity Template Language (VTL) available to use to transform the response however we need.
4. requestTemplates - this is where we define exactly how we want our request to be executed against DynamoDB.  We also have VTL available to us here, so that we can transform the request from how it comes into API Gateway to exactly how it needs to be for DynamoDB.  In this example I am using the intrinsic function Fn::Join to substitute in our DynamoDB table name (named the same as our stack) so that our table name is not hardcoded.
5. httpMethod - For DynamoDB actions the httpMethod from API Gateway to DynamoDB should always be POST.

One last edit we should make to our template.yaml file, is we will add a Globals: section and in there define OpenApiVersion: '3.0.1'.  This setting is necessary to resolve a bug with AWS SAM and without this setting we end up with two Stages being created in API Gateway - the stage Prod that we are specifying and an additional stage named Stage.  I usually create the Globals section in template.yaml after Description (at line 3), the additional block will look like:

Now we can run sam deploy (if this is your first time, run sam deploy --guided and I suggest allowing it to save your configuration to a file) to update our CloudFormation stack.  When AWS SAM completes updating our CloudFormation stack it will return the URL to our API Gateway as WebSiteOrigin.  For me the URL was https://40hfrzhqoj.execute-api.us-east-1.amazonaws.com/Prod.  We can browse to that URL with our sample record's sk value (/sample/post-1) appended to the end, and you will see a display like below:

This is displaying the values we set in that DynamoDB sample record to our browser, via API Gateway.  Now we probably want this information to be displayed in a nicer way than this, so we need to add some HTML and accompanying CSS.  For that I will turn to w3schools.com which has many prebuilt HTML templates to choose from. I will use their blog template.

I made some minor changes to that template, removing items that we will not cover adding functionality for at this point (most popular posts, tagging posts, comments) and removing placeholder images. We can add that functionality later in this series if it is desired.

The page template is somewhat large and is quite distracting when defined within the CloudFormation or OpenAPI template files, so I opted to move it to another file and import it from there into a CloudFormation mapping (another file cannot be imported into the openapi.yaml file).  In the future we will also need to associate this same page template with our home page, to avoid a lot of duplication, so having it defined elsewhere and able to be reference it where needed will make that cleaner as well.

To do that, let's first add the mapping section to our template.yaml file, I like to place the mappings between global and resources.

Then create the page.yaml file.  This is the template from w3schools, minus the sections I removed, with our VTL variables being placed within to put our articles stored in DynamoDB in to the template.

and finally let's replace the responseTemplates section in the openapi.yaml file with this below to use that new CloudFormation mapping for its response template.

Now, let's run sam deploy again and then browse to the page

That's what I was looking for.  I am not a front-end developer.  If you are, I'm sure you can make a page template that fits your style much better, but for me, this works.

Please note that, I have noticed for the API Gateway definition to update and deploy the changes, the openapi.yaml file needs to be modified.  Just modifying the page.yaml file that is referenced within it via a mapping is not enough, so I usually just make minor edits to the description field at the top of the OpenAPI file, like add a 1.

Our project directory at the end of this post is available here.

Thanks for reading.  If you have any feedback or questions, please leave a comment or message me on Twitter/LinkedIn (links on the right side bar).

Continue with the next article in this series.