Video Description

Having worked closely during the last years implementing and fixing DynamoDB implementations, I've been able to see some recurring errors and misunderstandings, and the root cause in most scenarios was trying to use it as you would with an SQL database. The goal of the task is to highlight the differences between SQL and NoSQL databases and showcase the most common errors with easy ways to fix them.

Organized by Cloud Turkiye
X https://x.com/CloudTurkiye
Kommunity https://kommunity.com/cloud-turkiye

TL;DR; This article covers how to implement a basic URL Shortener API with Custom Metrics. The sample project implements a Serverless Solution, deployed with the help of AWS CDK that relies on API GateWay, DynamoDB, Lambdas and Custom Cloudwatch metrics.

Introduction

Have you ever wondered how URL shorteners work under the hood? Or, even better, how to implement a similar solution that allows you to create custom analytics based on user behavior and types?

In this article, we’ll discuss what is needed to implement such features and provide a step-by-step guide (with a complete sample repository) for deploying them on your account.

Building the API

Overview

The API will have two different endpoints:

• A private endpoint to allow for redirect configurations to be created

• A public endpoint to redirect users to the desired URL

As one can see in the provided infrastructure Diagram, the resources required to build the API are very straightforward.

To build the API we took advantage of serverless AWS services, such as API Gateway, Lambdas, and DynamoDB.

The Infrastructure was designed as a proof-of-concept, but one could further improve it by adding IAM authentication, CloudFront, or WAF to further protect the API infrastructure.

Custom Domain with Route53

A custom Domain and an already configured Hosted Zone are prerequisites to deploying the provided CDK project, but one could easily remove that configuration and test the infrastructure with the default API Gateway domain.

As part of the project, we use Route53 to configure a custom domain for our API Gateway, since using the default domain wouldn’t act as a “URL Shortener” for most scenarios.

The CDK project expects the Hosted Domain to be already configured, but it will automatically generate the Domain Certificate and A Record for the new API endpoints to allow for HTTPS traffic.

Redirects DynamoDB Table

A Single DynamoDB Table will be used to store the required redirect configurations.

The Data model used by the sample project is straightforward, storing only a few attributes:

• urlId - Used as PrimaryKey and also as part of the shortened URL. The redirect URLs are generated as https://link.<your_url>/<urlId>

• ttl - Timestamp used to identify when the redirect record should be removed from the DynamoDB table

• originalURL - The actual URL to which incoming requests should be redirected to

• ttlInSeconds - Number of seconds for which the record was created for

The DynamoDB table is also configured to use the pay-per-request pricing model, time to live enabled on the TTL attribute, and to be deleted once the stack is removed.

Create URL endpoint

The Create URL endpoint will be the one responsible for creating and saving redirect configurations.

The configuration for this endpoint will be very straightforward, it will be triggered for any POST request received on the configured domain that provides a given urlId - such as https://link.<your_url>/<urlId>.

This endpoint will be private, requiring an API Key to be called, and a JSON schema was configured to allow API Gateway to validate any incoming request body.

Having API Gateway validating incoming requests allows for faster response times (in case of errors) and avoids invocations of the Lambda function for invalid requests.

The CreateRedirectURL Lambda in the sample project implements a basic approach, where it will:

1. Ensure the received input is correct

2. Build and send a conditional PUT request to DynamoDB, a condition expression will be added to avoid overwriting existing records with the same primary key

3. Based on the response:

   1. DynamoDB operation succeeded —> Build the success response and return the newly created redirect URL

   2. Operation failed —> Map the error and build the error response

As future improvements, one could implement more validations, link the created records to a given user / API Key, or even add some custom metrics to, for example, record how many redirects are created for given domains.

Redirection endpoint

The redirect URL endpoint is public and is the one responsible for creating the metrics and redirecting the user to the appropriate URLs.

This endpoint is configured to be triggered for every GET request received on the configured domain that provides a given urlId - such as https://link.<your_domain>/<urlId>.

The responsibilities of this Lambda are:

1. Validating incoming requests to ensure a valid path parameter has been provided.

2. Retrieve the redirect configuration from DynamoDB based on the provided urlId

3. Inspect the request headers and DynamoDB response to generate and store the custom metrics on CloudWatch

4. Based on the DynamoDB response

   1. If a redirect record was found —> return the success response with redirect configuration

   2. no record found or DynamoDB request failed —> Map and return the appropriate error response

The “magic” of this Lambda is how the success response is built, which allows browsers to redirect users to the provided URL. For Example:

{
    "statusCode": 302,
    "headers": {
        "Location": "https://lhidalgo.dev/url-shortener-custom-metrics"
    }
}

The redirection works thanks to the returned status code, as returning 3XX lets the browser know that the requested URL has been redirected. For our scenarios, the relevant 3XX status codes are:

• 301 —> Tells the browser that the URL has been moved permanently, the browser might use cached responses on consequent requests.

• 302 —> Resource has been moved temporarily, the browser will always call the original URL in consequent requests.

Since we want to track how many times a given URL is requested and create metrics based on the request information, the sample project will use the 302 status code. For other scenarios, where metrics are not implemented, or only unique user requests are relevant, using the 301 status code would be recommended to reduce the amount of received requests.

Custom Metrics

Overview

AWS CloudWatch will by default record some basic usage and performance metrics of deployed services, such as Lambda Functions, where metrics such as Invocation Count, Duration, and Error vs. Success Rate are automatically collected.

A part of the default metrics, CloudWatch also allows you to create custom metrics to track specific aspects of your application.

When working with custom metrics, one should be aware of the format in which they are stored, a quick overview of the most relevant aspects would be:

• Namespace —> could be seen as categories where multiple metrics can be created, especially useful for categorizing related metrics or differentiating them by service or feature.

• Metric Name —> names to identify specific metrics, for example RedirectRequest

• Unit & Value —> attributes to inform Cloudwatch what and in what format is being recorded and the actual value for the same

• Dimensions —> additional information, provided as Key-Value pairs, that provides additional data to the given metric.

Implementing Custom Metrics

There are multiple ways to send custom metrics to CloudWatch, a quick overview of the different options would be:

The provided sample project implements custom CloudWatch metrics using the aws-sdk v3 to keep the sample as vanilla as possible, the Lambda PowerTools metrics package is recommended for any scenario where response times are critical, as no additional latency is introduced.

As part of our example, we create a single metric called RedirectRequest which includes the following dimensions:

• shortName —> urlId / pathparameter of the redirect URL

• platform —> device platform/OS, fetched from the request headers

• deviceLanguage —> device language, fetched from the request headers

• browser —> browser used, fetched from the request headers

• domain —> the domain of the redirection URL, f.e.: lhidalgo.dev

• redirectURL —> the full URL where the user will be redirected to, f.e.: https://lhidalgo.dev/url-shortener-custom-metrics

• success —> flag to identify if the user was successfully redirected or not

Having these dimensions will allow us to implement different analyses, f.e.: language distribution of users accessing lhidalgo.dev.

Consuming Custom Metrics

CloudWatch metrics can be exported and consumed from third-party dashboards and analytics platforms, but the easiest approach is to use the AWS Cloudwatch Console, using the console one can explore all the available metrics and even create a custom dashboard to ease the recurrent access to given metrics.

As one can see in the above screenshot, the CloudWatch console also allows us to implement Metric Math expressions to aggregate the metric data to our desired format.

Taking advantage of this one can see how, thanks to the dimensions we provided to the metrics, we can now create a table view to analyze the redirect count to the different domains.

Deploying the provided repository

If you want to deploy the stack that was created as part of this article, feel free to fork the public repository and follow the next steps.

Requirements

To be able to deploy and use this application without requiring any changes you'll need:

• Node JS

• CDK & Bootstrapped AWS Account

• A Custom Domain and a configured Route 53 Hosted Zone

Deployment steps

1. Fork & Clone the repository

2. Install the project dependencies npm i

3. Set the required environment variable DOMAIN_NAME to your custom domain. Examples:

   • Windows/CMD - set DOMAIN_NAME=domain.com

   • Bash - export DOMAIN_NAME=domain.com

4. Synthesize the Cloudformation template to ensure the configuration is correct npx cdk synth

   • Some errors might be thrown if the Route53 Hosted Zone doesn't exist or your current AWS role lacks the proper access to it

5. Deploy the application npx cdk deploy

6. (Optional) Delete the application once you're done using it npx cdk destroy

Using the API

1. Retrieve the following values of the Stack Outputs printed during the deployment in the previous step

   • UrlShortenerCustomMetricsStack.APIKeyID —> You'll need to replace the string <api-key-id> with the value returned

   • UrlShortenerCustomMetricsStack.customAPIUrlOutput —> You'll need to replace the <your_url> with the value returned

2. Retrieve the API Key value and use it to replace the <api-key-value> in the following examples, some options to do so would be:

   • Navigate to the AWS Console and retrieve it manually

   • Execute the following AWS CLI command aws apigateway get-api-key --api-key <api-key-id> --include-value --query "value" --output text

3. Create your first redirection URL

        curl --location 'https://<your_url>/exmaple' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key-value>' \
        --data '{
            "originalURL": "https://lhidalgo.dev/url-shortener-custom-metrics",
            "ttlInSeconds": 360000
        }'
   

4. The previous curl command will return the redirection URL as part of its body, the response should be "https://<your_url>/exmaple"

5. Open that link on any browser and you'll be redirected to the URL you sent as originalURL in the previous request

Conclusion

In conclusion, building a URL shortener with custom metrics using AWS services is easier than one could think of and allows you to self-host your solution giving you more flexibility into what statistics you want to create.

This article also showcases how easy it is to create custom CloudWatch metrics, which can be implemented in any existing project to increase the observability of the same and provide valuable insights into the behavior of your application and users.

References

• Complete sample repository

• CloudWatch Embedded metric format

• Lambda PowerTools metrics package

• Metric Math expressions

• CDK & Bootstrapped AWS Account

TL;DR
This article provides a brief introduction to DynamoDB and the key differences between SQL and No-SQL databases in order to better understand the common mistakes and how to fix them. Feel free to skip to the Key takeaways section to read the most relevant points.

Not in the mood for reading? Check out the recorded version of this article on YouTube

Introduction

Getting started with DynamoDB is fairly easy since there are a lot of examples and good documentation out there, but it’s as easy or even easier to end up using it wrong, due to a lack of knowledge.

During the last few years, the vast majority of mistakes I’ve seen have been due to misunderstandings or a lack of knowledge of how DynamoDB works and the differences between NoSQL and SQL databases.

This article aims to provide a brief introduction to DynamoDB and showcase the most common mistakes during its implementation and how one could solve them.

DynamoDB 101

The key aspects of DynamoDB could be described as follows:

• Managed NoSQL database by AWS: Designed to handle large volumes of data with low latency.

• High availability and automatic scalability: Automatically adjusts to demand without manual intervention (When configured to PAY_PER_REQUEST).

• Consistent millisecond performance: Ideal for applications that require fast response times.

• Supports flexible data models: Includes document and key-value tables, with secondary indexes for efficient queries.

• Global security and replication: Provides encryption and data replication across multiple regions for greater durability and availability.

Key differences: SQL vs NoSQL

The table above shows what I personally would consider the key differences between both Database types since, if you’re not aware of them, you’ll probably end up using one of them wrong.

For example:

• Schemas - No-SQL Databases don’t have a strict or predefined schema, meaning that you can store a mix of data types and structures in a single table.

• Data Consistency - In order to allow for high performance and availability, No-SQL databases are, in general, not capable of providing the data consistency we’re used to with SQL.

Both of these examples are key things to keep in mind when choosing what database matches best your project, as No-SQL and DynamoDB in particular might not always be the right fit for you.

Example Key Difference SQL vs DynamoDB

A part of the differences in how they are built and how they work under the hood, it’s also important to consider the differences in how services can interact with the databases since, as stated above, No-SQL DBs tend to rely on system-specific query languages.

For example, INSERT INTO in SQL and PutCommand on DynamoDB will behave differently, and not knowing the default behaviors of the systems you interact with can land you in, what seems like inexplicable bugs.

What we mean by that is that the PutCommand and UpdateCommand on DynamoDB will, by default, behave like an UPSERT command in SQL.

This means that if developers are not careful enough or there is a lack of validations before performing the action, you might end up overwriting records (losing data!) or with downstream errors created by records without all the required attributes (records wrongly created by an UpdateCommand).

Avoiding this behavior can easily be done by adding conditions to those commands.

Condition Expressions

Condition Expressions could be seen as the DynamoDB implementation of the WHERE clause, but limited to be executed only over a single record.

Introduction

Using them allows developers to specify what conditions should be met for a given action to be performed.

For example, if we want to avoid DynamoDB default UPSERT behavior on PutCommand and UpdateCommand it would be as easy as adding a condition to the command.

In the above example, we added a ConditionExpression to the UpdateCommand to ensure that DynamoDB only updates records where the primary key exists (aka. it will only update existing records and fail if no record was found for the given keys).

Idempotency Checks

But the usage of Condition Expressions doesn’t stop there. It allows us to streamline for example the implementation of idempotency checks.

Idempotency checks are usually used to avoid processing a single event more than once. This becomes especially useful on distributed or event-driven applications where, in most cases, a single event could be delivered more than once or two consumers could be processing it at the same time.

The usual implementation of this kind of check is using a database or cache to store a record for every event that has been or is currently being processed.

This means that the first step for a consumer lambda would be to:

1. Check if the Event has already been processed

2. Update the databases stating that the given event is currently being processed

The screenshot above depicts what we would call a bad idempotency check implementation as it is being done with two different DynamoDB operations and we can’t ensure that this will stop concurrent processing of the same event, as there will be some time lapse between the read and the write operations.

The correct implementation of an idempotency check using DynamoDB would be by using only one operation, either a Put or an Update command would work depending on if we need to persist any attributes stored by a previously failed execution.

The above sample implements a PutCommand with a condition expression that will only succeed if:

• attribute_not_exists(#pk) - This will only be true if no record is found for the given primary key, as it’s a mandatory attribute

OR

• attribute_exists(#pk) AND #status = :failedStatus - This condition will only succeed if a record is found but the status of the previous execution was set as FAILURE. Implementing this additional check allows us to seamlessly retry failed executions.

Business logic Checks

Condition Expressions not only allow us to implement idempotency checks, but also allow us to implement a condition on any Put or Update command.

Another good scenario for it could be the backend of a given marketplace, where we would need to perform some business logic checks before a given transaction is approved.

Similar to the previous scenario, developers might be tempted to implement the business logic as part of the code by making a read operation, performing any business logic, and finally making an update operation to store the final value.

This implementation would be flawed and probably generate some hard-to-find bugs in high-traffic scenarios, as no consistency can be ensured between the read and write operations and a wrong stock amount could be stored.

A better approach to this would be using Condition Expressions and, if there is a requirement for specific error messages, adding the ReturnValuesOnConditionCheckFailure to ALL_OLD.

By configuring your DynamoDB request that way, DynamoDB will throw a ConditionalCheckFailedException if the ConditionExpression is not met and provide the record details as it were when the condition was analyzed.

Developers would be able to access the error and error.Item to run any additional logic and choose the appropriate error message, based on what part of the condition could have failed.

Retrieving Data

Similar to Put and Update operations, No-SQL DBs also present a different behavior regarding how developers are expected to handle the retrieval of data.

Limitations

The most known limitation is that No-SQL databases perform poorly with access patterns and queries over attributes not part of the keys.

A part of that, and similar to the LIMIT statement in SQL, Scan and Query operations can only retrieve up to a maximum of 1 MB of data at a time.

This presents a limitation for those cases where you need to retrieve more information or, especially, if you pass any type of query condition to your request, as DynamoDB will analyze up to 1 MB and could for example return an empty response even if matching records are present in the table.

Pagination

To overcome that 1 MB limitation, developers are expected to implement pagination.

Implementing it is as easy as checking for the LastEvaluatedKey attribute in the Scan or Query response and passing it as the ExclusiveStartKey in the next request.

If this is developed as a recursive function, as shown in the above sample image, developers will ensure that all the records in a table or all records that match a specific query will be found and returned.

Batch Operations

Put, Update, Query and Scan operations are the most well-known operations, but there are also scenarios where there is a need of writing or reading multiple specific records at once.

Limitations

For those scenarios, people usually think of implementing a loop or multiple requests in parallel, which triggers are usually not the best approach.

On one side, having a loop retrieving information is usually already flagged as a bad practice by linters with rules like no-await-in-loop from ESLint.

This is due to the poor efficiency of having all those requests in sequence, which will increase the overall execution time of the function exponentially.

On the other side, developers might think that retrieving the data in parallel with a Promise.all or Promise.allSettled might be a good approach but this will also not scale well and be difficult to debug, as developers could face a maximum connection limit reached error.

The correct implementation would be to take advantage of the available Batch* operations of DynamoDB.

There are two different batch operations that can be used with DynamoDB:

• BatchGetItems - Operation that will allow us to retrieve up to 16 MB or 100 records from the same or different tables in a single request

• BatchWriteItem - As the name implies, this operation will allow us to write (PutRequest) but also to delete (DeleteRequest) up to 16 MB or 25 records to a single or multiple tables.

These operations are especially useful for aggregating multiple GetItem or Put/DeleteItem requests into a single call to DynamoDB.

Unprocessed Items

Similar to the Query and Scan operations and due to the 16 MB limit on the Batch* operations, developers should expect some requests to fail, either partially or entirely.

Any request that doesn’t respect the 100 record read and 25 record write limit will fail entirely, throwing an error without doing any modifications on the DynamoDB tables.

The 16 MB limit is a bit trickier, as one could expect those requests to fail partially, DynamoDB will do its best to read or write up to a maximum of 16 MB for a single request and, if any records are not processed, it will return those as part of the UnprocessedItems attribute in the response.

Developers should always consider this when using these types of operations and implement a recursive function accordingly that will retry any UnprocessedItems found in the response.

Conclusions

DynamoDB is a powerful and versatile NoSQL database that offers unique advantages for various workloads. However, to fully leverage its capabilities, developers must understand its specific behaviors and limitations. By mastering concepts such as condition expressions, pagination, and batch operations, developers can create more efficient, consistent, and scalable applications.

Developers should consider the following key points when implementing any workload that relies on or interacts with DynamoDB.

Key takeaways

• Put and Update act like UPSERTS: Using the PutItem or UpdateItem commands without adding any condition behaves like UPSERTS in SQL.

• Reducing calls with CONDITION EXPRESSIONS: Adding conditional expressions allows us to perform our logic in a single call and with data consistency.

• Query and Scan require paging logic: Query or Scan operations only operate on 1MB pages, paging is required to retrieve more information.

• Use Batch operations to reduce execution time*: A Batch* operation is more effective than multiple individual operations in sequence or parallel and can be used to aggregate operations to different tables into a single request.

• Use BatchGet to retrieve higher volumes of information: The BatchGet operation allows you to retrieve up to 16MB or 100 records compared to 1MB for Query or Scan operations.

• BatchGet and BatchWrite require retry logic: With Batch* operations it is essential to apply retry logic on UnprocessedItems.

TL;DR; This article covers the usage of DynamoDB BatchWrite and BatchGet operations, and how implementing them can help you improve the efficiency by reducing the amount of requests needed in your workload.

Introduction

Have you ever developed any type of workload that interacts with DynamoDB?

If so, you probably have encountered the requirement of retrieving or inserting multiple specific records, be it from a single or various DynamoDB tables.

This article aims to provide you with it by providing all the required resources and knowledge to implement the usage of DynamoDB batch operations and, as a bonus point, increase the efficiency of your current workloads.

What are Batch Operations?

Introduction

When talking about batch operations or batch processing we refer to the action of aggregating a set of instructions in a single request for them to be executed all at once. In terms of interacting with DynamoDB, we could see it as sending a single request that would allow us to retrieve or insert multiple records at once.

Common Bad practices

Continuing with the sample situation mentioned in the introduction, you may face the requirement of having to retrieve or store multiple records at once.

For that scenario, most junior developers might rely on looping over a set of keys and sending the GetItem requests in sequence or a mid-level developer might propose to parallelize all those requests using for example a Promise.all, but both approaches are flawed and won’t scale well.

On one side, the for-loop will even be detected by some linters (with rules like no-await-in-loop) as this implementation would increase the execution time exponentially.

On the other side, the Promise.all approach will be a tad more efficient by parallelizing the requests, but with high workloads, developers would end up facing issues like the maximum connection limit reached error.

Recommended Implementation

Now that we have gone over some bad practices in implementing it and that you have probably thought of a few projects that could be improved, we’ll dive into how we can take the most advantage of it.

DynamoDB offers two different types of operations BatchGetItem and BatchWrtieItem which we will take a look into as part of this article.

There is also BatchExecuteStatement for those using PartiQL, but we will leave that one for a future article to cover PartiQL in detail.

BatchGetItem

This operation type will allow us to aggregate up to the equivalent of 100 GetItem requests in a single request.

Meaning that with this operation we could retrieve up to 100 records or 16 MB from a single or multiple table at once.

BatchWriteItem

This operation, even if it only contains write as part of its name, will allow us to aggregate up to 25 PutItem and DeleteItem operations in a single request.

Similar to the previous option, we’ll still be limited by the 16 MB maximum, but we would theoretically be able to replace 25 sequential or parallel requests with a single one.

Pagination for Batch operations

Similar to the Scan and Query operations, using any of the above Batch*Item operations can incur in the scenario where the 16 MB maximum is reached and some type of pagination is required.

For Batch* operations this comes in the form of the UnprocessedKeys attribute that can be part of the response.

Developers are expected to check for this attribute in the response and, if desired, implement its usage as a recursive function to process them automatically.

Real-world Use Cases

Now that we are aware of all options and limitations regarding how we can process records in batch in DynamoDB, let’s see some scenarios that will showcase some real-life improvements.

Scenario 1: Retrieving Data from Multi-table Design Architecture

For this first scenario, let’s imagine we are looking to improve the performance of a REST API that, given an array of productId, will return us the list of desired product details with their respective stock and exact warehouse location. The data is stored in multiple tables, one for each data model (products, stock tracking, and warehouse product location).

Before

The initial implementation was developed by having a for-loop to go over all the provided productIds and sequentially retrieve all the required data from the different tables.

After

From that initial implementation, you should be able to detect two distinct flaws:

• no-await-in-loop - There is a loop with asynchronous operations inside, which is usually a bad practice, as all operations for a given operation will need to be completed before the next one can start.

• Sequential await getItem requests - This is also a bad practice, as the three operations are independent from each other and we’d ideally not want for them to be blocked by each other.

A better approach would look something like this:

1. Input Validation - Set a limit of maximum items to be requested to avoid requiring parallel BatchGetItem requests.
   For example - max. 100 items per BatchGetItem request and every product requires 3 GetItem requests means that a single BatchGetItem request can retrieve up to 33 product details.

   ⚠

   This step could be avoided and execute BatchGetItem requests in parallel, but there could be a chance of facing issues like the maximum connection limit reached error.

2. Build Payloads - a helper function will be needed to programmatically build the required payload for the BatchGetItem operations taking into consideration the different tables that need to be accessed for each product ID.

3. Recursive BatchGetItem - a helper function that recursively calls itself to ensure that all UnprocessedKeys are retried.

4. Response parsing - a helper function that transforms the BatchGetItem response to the given schema that the consumers are expecting for this API

Applying all these changes should significantly increase the efficiency and performance of the API.

Scenario 2: Inserting Data in a Single-table Design Architecture

The second scenario would imply a DynamoDB single table design architecture where we have a single table to store all the information needed for a Dashboard to analyze racehorses’ historical data. Records such as basic horse information, performance statistics, and race results are stored in the same table.

Before

Similar to the first scenario, we can see that the initial implementation is based on a set of sequential PutItem requests.

After

From that initial implementation, you should be able to detect two distinct flaws:

• no-await-in-loop - There is a loop with asynchronous operations inside, which is usually a bad practice, as all operations for a given operation will need to be completed before the next one can start.

• Sequential await putItem requests - This is also a bad practice, as the three operations are independent from each other and we’d ideally not want for them to be blocked by each other.

A better approach would look something like this:

1. Build Payloads - a helper function will be needed to programmatically build the required payload for the BatchGetItem operations taking into consideration the different tables that need to be accessed for each product ID.

2. Recursive BatchWriteItem - a helper function that recursively calls itself to ensure that all UnprocessedKeys are retried.

   💡

   This approach would only work to upload up to 25 records for a single horse.

Applying all these changes should significantly reduce the required time to upload all information.

Conclusion

Utilizing batch operations in DynamoDB is a powerful strategy to optimize your database interactions. By aggregating multiple requests into a single operation, you can improve performance, reduce latency, and manage resources more effectively. Whether you're dealing with multi-table architectures or single-table designs, batch operations offer a scalable solution to handle large volumes of data efficiently. As you continue to work with DynamoDB, consider integrating batch operations into your workflows to maximize the potential of your applications.

Recap of key points

• BatchGetItem can retrieve up to 100 records or 16 MB of data in a single request.

• BatchWriteItem can be used to insert or delete up to 25 records or 16 MB of data in a single request.

• Using Batch* operations can help you reduce the execution time considerably by aggregating requests that were currently being done in sequence.

Additional resources and references

• https://github.com/Lorenzohidalgo/dynamodb-batch-samples

• https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html

• https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html

• https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchExecuteStatement.html

This webinar briefly introduces DynamoDB, the most relevant differences between SQL and NoSQL Databases, the most common mistakes when interacting with DynamoDB, and how to solve them.

Video Description

Three cloud software engineers, Danielle Heberling, Ian McKay, and Lorenzo Hidalgo, provide an in-depth look at their roles and responsibilities, key tasks, and the challenges they face working in cloud computing.

📜Table of contents:
00:00 Meet the Cloud Experts: Introductions
00:12 What Does a Cloud Software Engineer Do?
00:45 The Role of a Cloud Architect
01:42 A Day in the Life of a Technical Architect
03:56 Software Engineer's Daily Routine
07:17 The Importance of Meetings in Cloud Engineering
10:09 Challenges in Cloud Engineering
14:13 Dispelling Common Cloud Misconceptions

This video is part of a series called "Working in the cloud ☁️". Where cloud computing software engineers talk about how is to work in the cloud, getting a job in this space, and advancing their career.

Check the whole playlist here: Working in the cloud ☁️

🧑🏽‍💻 Find our guests online:
- Danielle Heberling - Senior Software Engineer at Ensomata
Personal website: https://danielleheberling.xyz/
X: / deeheber
Github: https://github.com/deeheber
LinkedIn: / deeheber
Dev.to: https://dev.to/deeheber
- Ian Mckay - Cloud Principal at Kablamo
X: / iann0036
LinkedIn: / iann0036
Blog: https://onecloudplease.com/
- Lorenzo Hidalgo Gadea - Independent Contractor | Staff Engineer at Serverless Guru
Linkedin: / lorenzo-hidalgo-gadea
Blog: https://lhidalgo.dev/
X: / lhidalgo_dev

Credits

Video From Marcia Villalba, follow her on:
🐦 Twitter: / mavi888uy
🖇️ Linkedin: / marciavillalba
📧 Newsletter: https://marciavillalba.substack.com/
📺 AWS Spanish Youtube Channel: https://bit.ly/aws-esp-yt
📷 Instagram: foobar_codes
📚 All my Serverless Courses: https://marcia.dev/courses/
✍️ My blog - https://blog.marcia.dev

TL;DR;
This article covers how developers can take advantage of the serverless-gql-generator plugin for Serverless Framework to automatically generate new Postman Collections or Raw Requests for an AppSync API.

Introduction

A few weeks ago, I announced the release of a new Serverless Framework Plugin that I had been working on called serverless-gql-generator.

The idea for this plugin came from the difficulties faced during one of my projects where it was too time-consuming for developers to keep the sample requests and Postman Collection for every new schema update. This pain point was further intensified when we started to develop multiple interdependent AppSync APIs simultaneously, requiring multiple Postman Collections to be updated and shared across teams.

In this article, we will cover how to integrate the Serverless Framework plugin into your development flow and CICD pipelines.

Main Plugin Features

As of writing this article, the current version 1.2.1 of the plugin has the following features:

• Automatic GraphQL Request Generation - The plugin will generate new requests on demand or during deployment, ensuring they are always up to date with the latest schema version.

• Automatic URL & API Key Retrieval - The URL and API Key will be automatically populated with the latest AppSync configuration.

• Choose between Inline or using variable file input - Developers can configure the plugin to generate requests with Inline input or with a separate file for variable input.

• Exports requests to independent Files and Postman Collections - Depending on the use case, developers can configure the plugin to export the generated requests to independent .graphql files, a Postman Collect or both.

• Upload the generated files to S3 - As the icing on the cake, this plugin also automates the upload of the generated files to the configured S3 bucket.

Prerequisites

In order to be able to implement this plugin into your workflow you will at least need:

• Node JS installation

• AWS Account to deploy the API

• A project that uses the Serverless Framework to deploy an AppSync API - examples will be shown using this repository

• Postman, GraphBolt or any other tool to send requests and test the generated requests

Installation Process

Installing and adding the plugin to your project is fairly straightforward to accomplish by following two simple steps.

Install the plugin using NPM

Use the following command to install the plugin and save it as a devDependency in your project:

npm install -D serverless-gql-generator

Add the Plugin to your project

Add the plugin under the plugins list in your serverless.yml file

service: my-app

plugins:
  - serverless-gql-generator

Using the plugin

After adding the plugin to the plugins list, it will start generating the Postman Collections every time the service is deployed.

The experience can be improved further by configuring the plugin to match your needs better and by using the CLI commands to enable the request generation without the need to redeploy your service.

Overriding the default behaviour

The plugin's default behaviour is to generate (and save locally under the ./output/ folder) a Postman Collection.

This behaviour can be configured by overriding the defaults and adding any of the configuration attributes:

service: my-app

plugins:
  - serverless-gql-generator

gql-generator:
  schema:
    path: ./schema.graphql # Overrides default schema path 
    encoding: utf-8
    assumeValidSDL: true
  output:
    directory: ./output # Output directory
    s3: # Enables Upload to AWS S3
      bucketName: gql-output-bucket # Mandatory Bucket name
      folderPath: s3folder/path # Override Folder Path inside s3, defaults to `${service}/${stage}`
      skipLocalSaving: false # if the files should also be saved locally or not
    useVariables: true # use variables or have the input inline
    maxDepth: 10 # max depth for schema recursion
    rawRequests: false # set to true to generate raw requests
    postman:
      collectionName: test-name # Overrides colection name, defaults to `${service}-${stage}`
      url: https://test.com/graphql # Overrides url for postman collection
      apiKey: abc-123 # Overrides default API Key if any

Default Schema options

The plugin expects the schema to be in the root folder of the project and be called ./schema.graphql, Developers can update the configuration under gql-generator.schema in order to update the path or encoding of their schema.

gql-generator:
  schema:
    path: ./schema.graphql 
    encoding: utf-8
    assumeValidSDL: true

Default Request Generation Options

Overriding the configuration on how the requests are being generated can be done by updating the following attributes under gql-generator.output.

gql-generator:
  output:
    directory: ./output
    useVariables: true
    maxDepth: 10
    rawRequests: false

• output.directory - path to the directory where the generated files should be stored at

• output.useVariables - flag to decide if the generated requests should have inline input or dedicated variable files

• output.maxDepth - maximum allowed depth for the generated requests, used to avoid infinite recursions in the requests

• output.rawRequests - flag to indicate if the raw requests (.graphql files) should also be stored. This flag has to be set to true if output.postman is set to false

Default Postman Collection Configuration

The plugin will, by default, generate a Postman Collection that will be called based on ${service}-${stage} and fetch the URL and API Key from the deployed API.

gql-generator:
  output:
    postman:
      collectionName: test-name
      url: https://test.com/graphql
      apiKey: abc-123

# OR

gql-generator:
  output:
    postman: false

Developers can override this configuration by updating the following attributes:

• output.postman - can be set to false to avoid the Postman Collection being generated, for that scenario output.rawRequests will be required to be true

• output.postman.collectionName - used to override the name to be used for the generated collection

• output.postman.url - used to override the API endpoint, especially useful if the API has a custom domain configured or you want to use the path to the CDN or Proxy

• output.postman.apiKey - used to override the API KEY to be used to authenticate the requests

Uploading files to S3

The output is only saved locally by default on the machine that generates the files, but there is the option to upload the files to S3 at the same time, making it even easier to share the results with other developers or teams.

gql-generator:
  output:
    s3:
      bucketName: gql-output-bucket
      folderPath: s3folder/path
      skipLocalSaving: false

In order to enable the export to S3 features, developers will need to update the following configuration under gql-generator.output.s3:

• output.s3.bucketName - mandatory field, has to contain the name of an existing bucket

• output.s3.folderPath - used to override the folder path in S3 where the files will be stored, by default it will create the following folder structure to store the files ${service}/${stage}

• output.s3.skipLocalSaving - flag to indicate if the files should be stored locally or only uploaded to S3

CLI commands

Developers might want to trigger the request generation without wanting to redeploy the API again, the plugin exposes some CLI commands to allow for that scenario.

Schema Validation

When creating or updating a Schema developers might want to validate that it's formatted appropriately.

The plugin exposes the following command to allow developers to validate the provided schema:

serverless gql-generator validate-schema

Once the above line has been executed on the terminal, it will prompt any possible issues or confirm that the schema is valid and ready to be used.

Requests generation

By default, the plugin generates all requests on every deployment, but there could be a scenario where one would like to generate them without deploying the API again.

Developers might use the following command to trigger the Request generation:

serverless gql-generator generate

Once executed, the plugin will generate all requests based on the configuration.

This command can be especially useful to confirm that the plugin is configured as expected or to generate the requests again in case the output folder has been added to .gitignore.

CI/CD integration

This plugin is easily integrated into one's CI/CD pipeline as it will be triggered automatically during the deployment process.

To access the generated files, developers might choose between:

• Workflow Artifacts - Configuring the pipeline to export the artifacts generated during the process would be equivalent to generating the files locally, but the developers would need to download them from the workflow execution.
  This approach is preferred for example for feature branches, where the output might change multiple times during the development.

• S3 Export - Output files will be uploaded automatically to S3 for easier access and sharing.
  This is the preferred approach for stable or shared branches, such as dev or main.

Conclusions

Adding the serverless-gql-generator plugin to your stack can help you and your team save time by automating the process of generating and sharing GraphQL requests.

I would love to hear about your experience using the plugin. Please use GitHub Issues to report any issues while using the plugin or requesting new features.

TL;DR;
This article explores DynamoDB condition expressions, highlighting their potential to enhance database operations. They help prevent accidental data overwriting and facilitate conditional updates. The article also details how to handle errors efficiently when condition checks fail, thus reducing the need for additional requests. By leveraging these expressions, developers can create more efficient and robust applications.

Introduction

Are you tired of your PutItem operations overwriting existing items?
Or your UpdateItem inserting a new object if the provided keys don't exist?
Are you still reading an object before updating it to ensure its current state?

If you replied to any of the above questions with a yes, the title triggered your inner refactoring freak or you're just keen to learn new approaches, then this article is for you. In this article we will discover and learn how to take the most advantage of (what I think) is a somewhat unknown feature: DynamoDB Condition Expressions.

DynamoDB Expressions

When working with DynamoDB developers use expressions to state what actions or conditions they want DynamoDB to process.

There are different types of expressions that developers can use:

• Projection Expressions - Similar to the SELECT statement in SQL, this type of expression is used to select what attributes you want DynamoDB to return when reading objects. By default, DynamoDB returns all attributes (same as using SELECT *).

• Update Expressions - Similar to the UPDATE statement in SQL, this expression is used in the UpdateItem requests to specify what changes you want to apply to the desired object. Developers can ADD, SET, REMOVE or DELETE attributes.

• Condition Expressions - This article's star of the show; could be compared to the WHERE clause of a SQL statement. This expression type will allow developers, as the name implies, to ensure a condition is met before the data is manipulated.

Using Condition Expressions

Developers can use condition expressions in any DynamoDB operation that manipulates data, such as PutItem or UpdateItem, and using such expressions opens the door to a whole new set of business logic and fail-safes that can be implemented without adding any additional requests to DynamoDB.

Avoid overriding existing objects

DynamoDB will, by default, override any existing data if an PutItem operation is triggered with existing keys.

There are scenarios where one would like to store a new object but only if it doesn't exist, for example, if we want to do some kind of idempotency check or if we want to avoid overriding existing data.

To do that, one could approach the issue by doing a Get/Query and only triggering the Put if the item doesn't exist, but using condition expressions allows us to do everything in a single request:

  const command = new PutCommand({
    ...,
    ConditionExpression: "attribute_not_exists(#id)",
    ExpressionAttributeNames: {
      "#id": "PK",
    },
  });
  await client.send(command);

In the above example snippet we're doing a PutItem request and adding the condition expression of attribute_not_exists(#id), this will indicate DynamoDB to only store the provided object if the current primary key (PK) is not in use.

By doing it, DynamoDB won't override any existing data and will also throw an error if the condition is not met (an object already exists).

Full example here.

Update only existing items

Similar to the insert, DynamoDBs behaviour on UpdateItem can also be a tad counter-intuitive, as it will execute and UPSERT operations and not an UPDATE.

For some scenarios it won't be an issue to always execute UPSERT operations by default, but in general one will want the UPDATE operation to fail if the record doesn't exist to avoid creating new records with only partial data that will probably trigger errors downstream.

Implementing that change is very easy, as one just needs to add a simple condition expression as follows.

    const command = new UpdateCommand({
      ...,
      ConditionExpression: "attribute_exists(#id)",
      ExpressionAttributeNames: {
        "#id": "PK",
      },
    });
    await docClient.send(command);

In the above example snippet we're doing a UpdateItem request and adding the condition expression of attribute_exists(#id), this will indicate DynamoDB to only update the desired object if the current primary key (PK) exists.

With this condition, if DynamoDB can't find an update with the provided keys, the current primary key (PK) will not exist and the condition would fail, meaning that the UpdateItem request will throw an error.

Full example here.

Conditional Updates

But the magic of Condition Expressions doesn't stop on avoiding unexpected behaviours from DynamoDB, they open a whole new range of possibilities.

For example, let's imagine a scenario where, during the login flow, you want to check if the account is frozen or not (user should not be able to log in) and if the account is active, update a field storing the timestamp and device information of the current login.

For this scenario, one could first query the data to check the account status and if the check is successfull send another request to update the object with the desired login information. This approach is technically correct and would probably work for most requirements, but it opens the following concerns:

• Number of Requests - The most common scenario will be that the account is not frozen and the login should succeed, meaning that for almost all logins two requests will be sent to DynamoDB.

• Data Consistency - This approach would be unable to handle or control any change on the data between both requests, meaning that, if the account is being deactivated at the same time, the login could succeed when it should have failed.

With the use of the Condition Expression we can move that business logic to be execute on DynamoDBs side.

    const command = new UpdateCommand({
      ...,
      ConditionExpression: "attribute_exists(#id) AND #obj.#key = :expected",
      ExpressionAttributeNames: {
        "#id": "PK",
        "#obj": "accountInformation",
        "#key": "isFrozen",
      },
      ExpressionAttributeValues: {
        ":expected": false,
      },
    });
    await docClient.send(command);

In this example snippet we're adding the condition expression of attribute_exists(#id) AND #obj.#key = :expected, this will indicate DynamoDB to only update the desired object if the current primary key (PK) exists and if the nested attribute accountInformation.isFrozen is set to false.

With this condition, we move the business logic to check the account status to be executed by DynamoDB directly, meaning that the object will only be updated if the condition is met. This way we only need to consider that the login should only fail if the UpdateItem request has failed.

Full example here.

Handling Conditional Check Failures

Now we know how to implement the condition expressions but we are missing what to do when the condition fails.

What if the expression contains multiple conditions and we want to have a custom error message depending on wich condition failed, should we trigger a new request to query the object?

The answer is no, and this is probably one of the hidden features that will help you the most. At this point, you are probably aware of the ReturnValues option to configure what information you would like DynamoDB to return, but did you know there is also ReturnValuesOnConditionCheckFailure?

It works similarly as the ReturnValues option, but with only two available options:

• NONE - the default, the thrown error won't have any information regarding the current object attributes and values.

• ALL_OLD - setting this option will request DynamoDB to throw an error that contains the old (current) object information in the response.

  try {
    const command = new UpdateCommand({
      ...,
      ReturnValuesOnConditionCheckFailure: "ALL_OLD",
    });

    const response = await docClient.send(command);
    return response;
  } catch (error) {
    if (!(error instanceof ConditionalCheckFailedException)) throw error;
    const oldRecord = unmarshall(error.Item);
    // Apply any logic to check why the update failed
  }

The above snippet showcases how one could approach the error handling for conditional expressions with three simple steps:

1. Set ReturnValuesOnConditionCheckFailure: "ALL_OLD" to ensure you receive the object information if the condition fails.

2. Ensure you only catch the expected exception types by re-throwing any error that is not an instance of ConditionalCheckFailedException.

3. Retrieve and unmarshall the record data from the returned error with unmarshall(error.Item). The Item value will be the marshalled object that we tried to update, it's important to unmarshall it or ensure we access it's properties respecting the marshalling.

After those steps have been implemented, one can add any additional desired business logic to check why the operation failed and handle the error appropriately based on which of the conditions failed.

Full example here.

Conclusions

In conclusion, DynamoDB condition expressions provide a powerful tool that can greatly enhance the efficiency and reliability of your database operations. They allow developers to implement complex business logic directly within their database operations, reducing the number of requests and mitigating risks of data inconsistency.

This feature can help prevent unintended data overwriting, ensure updates only apply to existing items, and enable conditional updates based on specific criteria. With the ability to return current object data when condition checks fail, developers can handle errors more effectively without making additional requests.

By fully utilizing this feature, you can unlock the true potential of DynamoDB and create more robust and efficient applications.

Serverless Guru has organized a Serverless Holiday Hackathon where participants compete during the first half of December 2023 to see who can develop the best holiday-themed chat application that uses any LLM.

As part of the Hackathon organization, we developed a demo app to showcase to participants how one could build a relatively simple chat application where the LLM acts like Santa.

This article is meant to aid any participant who might be currently stuck with their project while also acting as an example of the article they need to write as part of the project submission.

Our Demo will be live until the end of December 2023 and can be found under the following link: https://santa.serverlessguru.com/

Demo Video

Some Loom videos have been recorded to showcase the demo application and to provide more context before we do a deep dive into the actual Back-End architecture and development process.

FE Example

The following video provides a quick introduction to the application, its capabilities, and how one could use it from the Front-End app.

API Example (Postman)

Another video has been recorded of the actual WebSocket API behaviour to provide more context into the actual workings of the developed API.

Challenges Faced During Development

As part of this section, and before showcasing the full solution, we want to introduce some of the challenges we faced during the development and how we resolved them.

Connecting to an LLM

The main requirement of the Hackathon is that the app has to be holiday-themed and take advantage of the use of an LLM.

Conversation Chain and Memory

We introduced the usage of the Langchain JS framework to simplify the implementation of a Conversation Chain and the storage of the Conversation History.

Enabling this allows the model to have access to the context of the full conversation and generate more context-aware and valuable responses.

Getting Streamed Responses

As the cherry on top, we also wanted to implement streamed responses to the user.

This would allow us to generate a more interactive experience on the Front End by completing the response dynamically.

To be able to receive streamed responses and use a conversation chain, we needed to implement a callback on Langchain.

Here is a simplified implementation example:

await chain.call({ input: userInput }, [
    {
      async handleLLMNewToken(token) {
        streamedResponse += token;
        console.log(streamedResponse);
      },
    },
  ]);

The full code snippet can be found in the following repository.

Avoiding Timeouts - WebSocket API

As mentioned during our Webinar Building Your First Serverless API with Langchain one of the challenges developers will face is the execution time taken by the LLMs to process some prompts.

During the Webinar, we presented different options, such as AppSync Subscriptions and WebSocket APIs.

In this case, we decided to develop a WebSocket API, which resolved the need for bi-directional communication but introduced some additional challenges.

Decoupling long-lasting execution

Similar to any other API, a WebSocket API still has a 30-second timeout for the Back End Resources to confirm a message was received correctly.

The main idea is to decouple the logic into two different flows.

The first flow, as shown in the image above, is the one limited by the 30-second timeout and is responsible for handling incoming messages. The Message Handler Lambda would process any validation logic required, trigger an event, and reply to the user stating that the message was received gracefully.

The second flow is completely decoupled and can take as long as needed being only limited by the maximum execution time of the lambda and the 10-minute idle timeout of WebSocket APIs. In this Flow, the Message Processor Lambda is triggered by the events generated by the previous flow, executes any processing logic, and takes advantage of the bi-directional communication capabilities to send as many messages as needed back to the user.

Authentication and State Management

One of the main issues in choosing a WebSocket API is the need to implement the correct state management logic to ensure that the messages are being processed in the required order and that no one tries to exploit the API.

To handle the correct usage and authentication we implemented the following state machine:

The most relevant parts of the implemented state machine are:

• No messages will be processed until the user sends a valid authentication message.

• If authentication fails, the state will be updated as 'Authentication Failed', and no further action/message will be processed.

• User prompts will be processed one at a time and only if the state is in 'Connection Ready' when the prompt is received.

Architecture Overview

After seeing the different challenges that we faced and how we resolved them, we are ready to jump straight into the final architecture.

As part of our final application, we developed two different APIs:

Management API

On one side we have the Management API, which is intended to handle part of the authorization logic.

As part of this REST API, we have two different endpoints:

• '/generateApiKey': This endpoint, intended to only be used internally, handles the API Key generation. It can be seen as an API Key vending machine. As WebSocket APIs don’t support API Keys, we’ll store the identifier and associated usage limits on a DynamoDB table.

• '/retrieveConfig/{configId}': This endpoint, used by the Front End application, is used to retrieve the API Key information necessary to send the authentication message as part of the WebSocket API.

WebSocket API

The “main course” would be the WebSocket API, the main API used to implement the Santa Chat application logic.

This API could be divided into the following sections:

Default Actions

Default actions, or routes, would be the ones handling the default/required functionalities.

As part of this section, we have the following routes:

• '$connect': This route is triggered for every connection request. For this route, we implemented some custom logic to create a new 'session' record for the received 'connectionId'. This newly created record is used to manage the different states and ensure we’re able to limit the usage as required.

• '$disconnect': This route is triggered whenever a connection is closed. Here we implemented some clean-up logic to delete any stored information linked to the current connection.

• '$default': This is the fall-back route, which is triggered when a route for the given action cannot be found. For our specific use case, triggering this route will always return an error message.

Custom Actions

As part of the default and required actions, we also implemented some custom routes/actions.

These new custom routes will handle the following logic:

• 'authenticate': This route will check that the provided API Key is valid and update the Session state accordingly. If the authentication is successful, a 'Authentication Completed' event will be added to the custom EventBridge bus. If it fails, no event will be triggered and the connection won’t accept any further messages.

• 'send_message': This route is the one responsible for handling any received user prompts. This Lambda will also ensure that the Session State is in the correct status and, if it is, it will add a 'Prompt Received' event to the custom EventBridge bus and set the new Session State.

Decoupled Events

The magic sauce, decoupling the events, could be the most relevant part of the architecture.

By decoupling the processing/requests sent to AWS Bedrock to an asynchronous process we ensure that our API should never timeout.

We defined and implemented the following events:

• 'Authentication Completed': This event is triggered automatically when the authentication process is completed. The main objective of this event is to trigger an initial prompt to Bedrock, that will start the conversation by introducing itself as Santa and setting up the appropriate context.

• 'Prompt Received': This event is triggered every time we receive a prompt. The SendMessage Handler Lambda will be responsible for formatting and sending the prompt to Bedrock and sending the streamed response to the user.

Next Steps

As mentioned in the article, the approach taken was to develop an MVP with minimal features to showcase how a simple chat application could work.

There is an almost infinite amount of possible next steps and improvements that could be done, here are a few that we could think of:

• Enable voice-to-text and text-to-voice transcription to take the application a step further and make it feel more like a real conversation and not just a chat.

• Improve Authentication and allow for persistent message history.

• Add any additional feature, such as implementing an Agent to allow the LLM to query another API to f.e.: List possible gift ideas or build a custom wishlist to send to Santa.

Conclusions

In conclusion, the process of building an AI chatbot, particularly one themed around Santa for our holiday hackathon, presented a number of challenges but also provided a rich learning experience.

From ensuring efficient handling of long-lasting executions to managing the state of WebSocket APIs, we navigated various complexities and came up with innovative solutions.

This project not only showcases the potential of Large Language Models (LLMs) in crafting engaging conversational experiences but also demonstrates the importance of a well-thought-out architecture in managing the unique challenges of real-time, interactive applications.

As we continue to explore the world of serverless applications and AI chatbots, we look forward to sharing more insights and learnings with our community.

TL;DR: This article discusses how to use AppSync Subscriptions to decouple long-running tasks from front-end requests in a serverless chat application. It provides a step-by-step guide to implement this solution, including an architecture overview, decoupling and processing steps, prerequisites, GraphQL schema, AppSync API configuration, DataSources and Resolvers, and Lambda function setup. The sample code and complete implementation can be found in the provided GitHub repository.

Introduction

When building APIs, developers often face the issue of long-running tasks timing out requests from the Front End or difficulty decoupling those longer tasks from the actual FE requests while informing it of the execution status.

In this article, and as part of the Serverless Holiday Hackathon, we will review how developers can take advantage of AppSync Subscriptions to decuple long-running tasks from the actual FE request.

Architecture Overview

The Hackathon challenges participants to build holiday-themed chat applications that use Generative AI.

While building such an application, developers will probably face the possible difficulties:

• Requests to Badrock or any other LLM API could entice long-running requests to generate longer responses, these could take longer than 30 seconds and timeout the requests

• Not knowing how to take advantage of streamed responses, which would provide the final user with a more interactive experience.

With this example, we will cover how to resolve both scenarios in two simple steps, while still leaving room for improvement and personalization.

Step 1: Decoupling

As the first step, we will need to decouple the front-end request from the actual processing. To do so, we can configure a JS Resolver to send the message to be processed to a SQS queue.

The flow would look like this:

1. The user sends a request to AppSync.

2. The JS Resolver creates a unique identifier for the received prompt and adds the message to the SQS Queue.

3. AppSync returns the unique identifiers to the User.

The User will need the response for the following step.

Step 2: Process and Notify

The second step will handle the prompt processing and notifying the user by sending a dummy mutation request that will trigger a subscription.

The flow for this step would be composed of the following steps:

1. The user subscribes via AppSync to updates on the streamedResponse mutation using the provided identifiers in the previous response.

2. The SQS Queue will trigger the Lambda for each message added to the same Queue by the above-explained mutation.

3. The Lambda Function will send a streamedResponse mutation request for all updates that we want to notify the user with.

4. Each request sent as a streamedResponse mutation will trigger subscribed users to be notified by every response that matches the filtering requirements.

Implementing the solution

In this section, we will go over how to implement the solution that we described in the previous step.

All details and code can be found in the following sample application repository.

Prerequisites

To correctly follow and deploy the sample application, developers will need to fulfill the following requisites:

• Node JS installation

• AWS Account to deploy the API

• Postman or GraphBolt to send requests and test the flow

GraphQL Schema

A mock schema has been defined for this application, part of the schema can be seen here:

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

type Query @aws_api_key @aws_iam {
  getSessionId: ID!
}

type Mutation {
  sendPrompt(userPrompt: userPrompt!): promptResponse @aws_api_key @aws_iam
  streamedResponse(streamedResponseInput: StreamedResponseInput!): StreamedResponse @aws_iam
}

type Subscription @aws_api_key @aws_iam {
  onStreamedResponse(sessionId: ID!): StreamedResponse @aws_subscribe(mutations: ["streamedResponse"])
}

The most important part of it is the auth directives for the mutations, where streamedResponse is only enabled for @aws_iam.

This is an important configuration aspect as we want only our Back End services to be able to trigger this mutation.

AppSync API

To configure the AppSync API using Serverless Framework we will be taking advantage of the Serverless AppSync Plugin.

appSync:
  name: ${self:custom.base}-appsync
  logging:
    level: ALL
    retentionInDays: 1
  xrayEnabled: true
  authentication:
    type: AWS_IAM
  additionalAuthentications:
    - type: API_KEY
  apiKeys:
    - ${self:custom.base}-key
  substitutions:
    accountId:
      Ref: AWS::AccountId
    queueName: decoupling-sqs
...

Some key insights from the above configuration:

• Cloudwatch can end up being expensive, but to avoid racking up a high bill we configured them to only be retained for one day. We kept the log level to ALL to ensure we can see all logs during debugging, but make sure to lower that for any production projects, AppSync Logs are very verbose.

• Multiple authentication methods, we want two different auth methods to ensure that: Our API is private and that we can limit who can trigger the streamedResponse mutation.

• Substitutions: AppSync resolvers don't support environment variables, a workaround for that would be to use substitutions. This feature will act as environment variables by substituting some mock text in the resolver code with the actual required values.

DataSources and Resolvers

Apart from the above API configuration we also need to ensure we configure the code that will resolve each operation and the different data sources used by them.

...
  dataSources:
    localResolverDS:
      type: "NONE"
    sqsDS:
      type: "HTTP"
      config:
        endpoint: !Sub https://sqs.${AWS::Region}.amazonaws.com/
        iamRoleStatements:
          - Effect: "Allow"
            Action:
              - "sqs:*"
            Resource:
              Fn::GetAtt:
                - MyQueue
                - Arn
        authorizationConfig:
          authorizationType: AWS_IAM
          awsIamConfig:
            signingRegion:
              Ref: AWS::Region
            signingServiceName: sqs
  resolvers:
    Mutation.sendPrompt:
      kind: UNIT
      dataSource: sqsDS
      code: "./src/appsync/sendPrompt.js"
    Mutation.streamedResponse:
      kind: UNIT
      dataSource: localResolverDS
      code: "./src/appsync/streamedResponse.js"

Key takeaways from this config are:

• Data Sources: What Resolvers use to fetch data and resolve operations. In this case, we configure two different types.

  • NONE: Used for resolvers that only rely on local business logic, without the need to retrieve/send any information

  • HTTP: Not all AWS services are supported to integrate directly with AppSync, but if it has an HTTP endpoint, you can trigger it via HTTP request. For example, SQS.

• Resolvers: In this section, we define what kind, data source and code will be used to resolve a specific operation or data type.

Decoupling Lambda

Once we have the API up and running, we can focus on how to configure a Lambda function to process all messages from the SQS Queue.

functions:
  sqsHandler:
    handler: src/decoupled.handler
    role: LambdaRole
    logRetentionInDays: 1
    environment:
      GRAPHQL_ENDPOINT: { Fn::GetAtt: [GraphQlApi, GraphQLUrl] }
      REGION:
        Ref: AWS::Region
    events:
      - sqs:
          arn:
            Fn::GetAtt:
              - MyQueue
              - Arn
          batchSize: 1

This configuration is not different than any other Lambda Function triggered by a SQS Queue. But there are still some takeaway points from this configuration:

• IAM Role: Developers will need to add and configure a custom IAM role for this Lambda role to be able to sign requests to AppSync.

• Log retention: Similar to the AppSync configuration, we want to limit the time that the logs are stored, in this case, the logs should be deleted after one day.

• AppSync API Endpoint: Something that developers can struggle with is getting the URL endpoint from the AppSync API generated in the same serverless.yml. To get that value one could use { Fn::GetAtt: [GraphQlApi, GraphQLUrl] } to resolve it during deployment.

Implementing the code

The code to complete the above example configuration can be found on the provided Github Repository, but the following is an example of one of the trickiest parts.

import { util } from "@aws-appsync/utils";

const accountId = "#accountId#";
const queueName = "#queueName#";

export function request(ctx) {
  const { userPrompt } = ctx.args;

  const msgBody = {
    ...userPrompt,
    messageId: util.autoId(),
  };

  ctx.stash.msgBody = msgBody;

  return {
    version: "2018-05-29",
    method: "POST",
    resourcePath: `/${accountId}/${queueName}`,
    params: {
      body: `Action=SendMessage&Version=2012-11-05&MessageBody=${JSON.stringify(
        msgBody
      )}`,
      headers: {
        "content-type": "application/x-www-form-urlencoded",
      },
    },
  };
}

The code sample is part of the JS resolver configured for the sendPrompt mutation. As part of this sample, we can learn:

• JS Resolver substitutions: When using substitutions with JS resolvers, developers need to make sure they define a variable const accountId = "#accountId#"; where the value will be replaced with the value provided in the configuration with the same name as the one between the #.

• Building a HTTP request: The returned object by the request function is an example of how to build an HTTP request for accessing/triggering the SQS API.

Conclusions

In conclusion, AWS AppSync Subscriptions can effectively decouple long-running tasks from front-end requests in serverless chat applications.

By implementing the two-step process of decoupling and processing with notifications, developers can enhance user experience and avoid request timeouts.

The provided sample code and repository offer a practical guide to implementing this solution, showcasing the use of GraphQL schema, AppSync API configuration, data sources, resolvers, and Lambda function setup.

References

• Sample Github Repository: https://github.com/Lorenzohidalgo/appsync-decoupling-sample

• Serverless AppSync Repository: https://github.com/sid88in/serverless-appsync-plugin

TL;DR: This article provides a step-by-step guide to setting up a new AppSync JS Resolvers project, including ESLint configuration, unit testing, and debugging. Learn how to use the AWS CLI command for testing resolver code, understand AppSync logs, and explore best practices for writing comprehensive unit tests.

Introduction

In the first article of this series, Mastering the Basics of AppSync JS Resolvers: A Quick Start, I shared the key insights I wish I had received before embarking on AppSync JS Resolvers.

In this article, as a follow-up to the first one, we will dive deeper and provide detailed steps to set up a new project and what the first steps would look like.

ESLint setup

For new joiners, ESLint is a static code analysis tool for identifying problematic patterns found in JavaScript code.

As we already know, the APPSYNC_JS runtime has some limitations, where not everything is allowed. There are some JS operations that are not supported and can't be used while developing JS Resolvers (for example: try-catch, async/await, third-party libraries, ...).

Thankfully, the AppSync team published an ESLint plugin to allow users to detect those unsupported operations and solve them before trying to push the code.

The provided plugin is fairly limited in what it will allow you to use and it was intended to be used only for developing we recommend to only set it up for the folder containing the resolver code.

General Configuration

As for the desired general ESLint configuration, you can go ahead and configure everything like you're already familiar with.

For our example, we went with installing:

• ESLint

• Prettier

• airbnb-base plugin

All your configurations can be at the root of the project, you just need to take into consideration that whatever you configure at the root will affect all files in the project.

Configuration for Resolvers

In order to also apply the ESLint plugin provided by AppSync but limit it to only the resolver code, you will need to:

• Create a folder where you will store all the AppSync Resolver code

• Add a new .eslintrc config file in that folder

That new config file could be like this:

{
  "extends": ["plugin:@aws-appsync/base"]
}

If you only need or want to implement the base linting configuration. Once configured, you will be able to see the linting issues detected by the different plugins.

In this case, we can see the following:

• Try statements are not supported - detected by the aws-appsync ESLint plugin, since try-catch statements are not allowed in JS resolvers.

• Unexpected console statement - detected by the default general rules that were applied project-wise in the prior step.

As always, I highly recommend you go through the official documentation to check all the different configuration options that are available.

Unit Tests

Following best practices, you should always aim to write extensive and comprehensive unit tests to ensure that the developed features work as expected and consequent updates don't break existing functionality.

When writing unit tests for JS resolvers you might find different complications that you might or might not know how to solve.

Here are the solutions that we found for two of the most common requirements (for jest testing framework).

Mocking @aws-appsync/utils

As of right now, there isn't an easy way to mock @aws-appsync/utils or test resolvers using that dependency using jest.

Mocking runtime global

While developing Javascript resolvers, one might also end up using runtime functionalities, for example, runtime.earlyReturn(...) to break the current execution.

export function request(ctx) {
  const { stash: { triggerEarlyReturn } } = ctx;

  if (triggerEarlyReturn) {
    runtime.earlyReturn({});
  }

  // Some logic that shouldn't be executed
  const result = { ... }
  return result;
}

If not handled properly, all unit tests written for those resolvers will fail directly, as these runtime functions are not defined in your local runtime environment.

const {
  request,
} = require('./myResolver');

describe('My test set', () => {
  const earlyReturnMock = jest.fn();

  beforeAll(() => {
    global.runtime = {
      earlyReturn: earlyReturnMock,
    };
    earlyReturnMock.mockImplementation(() => {
      throw new Error('earlyReturn');
    });
  });

  test('Happy Path Test', () => {
    const ctx = { ... };
    const expectedResult = { ... };
    const result = request(ctx);
    expect(result).toEqual(expectedResult);
    expect(earlyReturnMock).not.toHaveBeenCalled();
  });

  test('Early Return Test', () => {
    const ctx = { ... };
    expect(() => request(ctx)).toThrow('earlyReturn');
    expect(earlyReturnMock).toHaveBeenCalledTimes(1);
  });
});

By mocking and enabling it as shown in the example, the tests will stop breaking and one will be able to further test the expected behaviours.

Debugging Resolvers

One of the biggest pain points I faced when I started developing resolvers was how one could be able to debug them and find possible issues before they actually broke the CI/CD pipeline.

Here are a few insights on how one can do it with only the use of official AWS services.

AWS CLI command

The AWS CLI can be used to test resolver code by executing the following command:

aws appsync evaluate-code \
  --code file://resolver.js \
  --function request \
  --context file://context.json \
  --runtime name=APPSYNC_JS,runtimeVersion=1.0.0

Where, aws appsync evaluate-code tells the CLI the action that you'd like to do (in this case, evaluating the code for a resolver) and where one will need to provide the following input arguments:

• --code: This argument is used to point to the code that one wants to test. the prefix file:// should be used when pointing to local files.

• --function: This argument defines the function to be evaluated, the possible options are either request or response

• --context: This argument is used to provide the context object that will be used to call your code.

• --runtime: This argument is used to select the runtime that will be used to evaluate the code. For JS resolvers one should always use name=APPSYNC_JS,runtimeVersion=1.0.0

One could expect the response of the execution to be in the following format:

{
   "error": { 
      "codeErrors": [ 
         { 
            "errorType": "string",
            "location": { 
               "column": number,
               "line": number,
               "span": number
            },
            "value": "string"
         }
      ],
      "message": "string"
   },
   "evaluationResult": "string",
   "logs": [ "string" ]
}

The values that one could expect for each attribute are:

• error: When provided in the response, this key will provide the details for the error thrown by the evaluation of the uploaded code.

• evaluationResult: This key will contain the response of the evaluated function (whatever the function returns) in string format, meaning that if an object is returned, one will receive the stringified value of the same.

• logs: This key will provide a list of all the generated logs during the code evaluation. This is especially useful to test/check for the output of any console.log used in the code.

Please review the Official CLI command documentation or the official debugging guide for a more detailed description.

Sending Requests

The last step of testing and debugging your code will be to execute some End-to-End testing of your whole AppSync API.

In order to do this one could choose from a multitude of different tools to build and execute or send requests.

Here is a list of my recommended ways to do so:

• AWS AppSync console: The built-in and probably easiest way of building and sending requests. My favourite feature of this approach is the built-in method to build the requests by selecting and providing only the required fields.

• Graphbolt: My go-to tool when it comes to AppSync requests. Graphbolt allows you to test, debug and monitor your AppSync APIs from within the same UI. It even shows the Cloudwatch logs and X-Ray traces for each request!

• Postman: There is probably no description needed here, but this would be the go-to if you're working on different API types at the same time or need to be able to easily share collections with your team.

Understanding AppSync Logs

One of the most challenging parts of debugging AppSync could be understanding the logs and all the information provided in them.

I highly recommend the latest article from Benoît Bouré where he explains Debugging AWS Appsync APIs with Cloudwatch logs.

As a little easter egg, make sure to check the last section of the blog post, where he goes over how one could use Graphbolt to make this process even faster and easier to understand.

Conclusion

Between the last article Mastering the Basics of AppSync JS Resolvers: A Quick Start and this one, we provided the most relevant information and first steps developers need to consider when getting started with an AppSync API that uses JS resolvers.

That said, now is the point for every reader to start developing its own API in order to better understand how AppSync works and the benefits that it could bring to your organization.

One of the biggest pain points that we have faced so far when developing for AppSync or GraphQL APIs with constantly changing schemas has been to generate or keep the collections updated.

In the next article, we will go over how the package gql-request-generator was developed and how one could use it (or even integrate it in a CICD pipeline) to easily keep all Collections up to date.

AWS X-Ray is a service that collects data from all the requests handled by your services, allowing you to visualize and analyze it. It generates service maps, response time or duration distribution, and segment timelines to help developers debug performance issues and improve the overall performance of their code. Setting up X-Ray is straightforward and only requires a few simple steps, including enabling tracing and configuring what X-Ray should capture.

Introduction

Observability and code profiling is, at least in most cases, an afterthought that comes into play once it’s too late. Most developers start thinking about it when they face issues, timeouts, or bottlenecks that they can’t easily resolve or justify with only the execution logs.

There are a lot of third-party observability and profiling third-party tools out there that might be useful, for example, Sentry.io, Dynatrace, or DataDog. But if you want to stay inside the AWS ecosystem, and have an almost effortless integration, AWS X-Ray would be the tool to choose.

In this article, we will go over what AWS X-Ray is, how we can enable it, and how it will help us to better understand and debug the performance of our code.

What is AWS X-Ray?

As per AWS's words, “AWS X-Ray is a service that collects data from all the requests handled by your services and allows you to visualize and analyze it.” In other words, AWS X-Ray is for requests and services interaction what Cloudwatch is for execution logs.

When enabled and correctly configured, AWS X-Ray will collect and measure all service interactions for a specific request. This information will be stored and made available for analysis in the following ways:

1. Service Maps

AWS X-Ray generates service maps to allow for a visual understanding of how all different services interact with each other. Using a somewhat simple CRUD orders API as an example; we’d be able to see the following two service maps:

Global Service Map:

This type of service map will allow the user to understand and visualize how all the services under the same domain interact. In this screenshot, we can see that the end client interacts with a single API Gateway which, depending on the request type, depends on a set of Lambda functions to process the request and interact with a single DynamoDB table.

Trace Service Map:

The second kind of service map can be found on the console when reviewing a single trace and will contain only the interactions with services for that single trace or user request. This is the one that will help us the most when trying to debug performance issues for different features since we’ll be able to see what services are being used and how the different executions took place.

For example, in the provided screenshot we’re able to see that the execution failed since the nodes displayed for both API Gateway and AWS Lambda are in an error state.

2. Response Time or Duration Distribution

AWS X-Ray also provides a distribution diagram for groups of traces. This is specifically useful when trying to understand the overall performance of your service, how it affects the end users, and how much effort should be put into improving the service for each scenario.

For example, performance issues should be prioritized differently if it affects only 0.5% of all requests or if it affects 50% of them.

3. Segment Timelines

Segment timelines are the most detailed diagrams that X-Ray will provide and allow developers to understand exactly how and when each service is being used.

These timelines are specifically useful when debugging performance issues. For example, in this provided example we can see that the culprit for the long execution time is the Lambda Initialization (a.k.a. Cold Start) which took 859ms to complete, and that most of the execution time for the AWS Lambda invocation itself was spent requesting the deletion of the item in DynamoDB.

Enable AWS X-Ray in AWS Lambda

Enabling AWS X-Ray on your AWS Lambda functions is very straightforward, and can normally be accomplished within a few minutes following two simple steps.

Step 1: Enable AWS X-Ray tracing on Your Services

The easiest way to do so is to enable it from your IaC template. For example, when using Serverless Framework, you can just add the following attributes under 'provider.tracing' to enable AWS X-Ray on all your defined AWS Lambda functions and the generated API Gateway.

Another option, in case you’re not deploying your services with an IaC template, would be to enable it manually through the AWS Console.

You will just need to head over to your Lambda configuration section and Edit the 'Monitoring tools' section by enabling the tracing switch.

Step 2: Configure What X-Ray Should Capture

After enabling AWS X-Ray on your Lambda function, you will also need to add the 'aws-xray-sdk-core' library to your project's dependencies and configure it to add the required traces.

Capturing AWS SDK Usage:

Wrapping the 'aws-sdk client' with the showcased functions will allow AWS X-Ray to capture and trace how the client is being used. For a Node JS project, there are two different configurations depending on the aws-sdk version your project is currently using.

If you are using aws-sdk v2, you'll only need to wrap the library once and it will have a “global” effect.

For example, with the provided code snippet, AWS X-Ray will be able to capture all requests done with the v2 SDK, independently of the client (SSM, DynamoDB, S3, etc).

When using the v3 SDK, the developer will need to add the AWS X-Ray wrapper to all the instantiated clients.

This snippet, for example, will allow AWS X-Ray to only capture the requests made with that specific DynamoDB client. If you instantiate another DynamoDB client (or for any other service) in another file without adding the wrapper, AWS X-Ray won’t be able to capture the usage.

Capturing HTTPS Requests:

In some cases, your project may also use some HTTPS requests to, for example, access third-party APIs which you’d also like to capture.

In order to do so, and similarly to wrapping the v2 SDK, you can add the above snippet to your index file to allow AWS X-Ray to capture all the HTTPS requests made by your code.

Adding Custom Subsegments:

Custom subsegments will allow AWS X-Ray to capture and measure the execution time of the desired part of your code.

One may add a custom segment by following the provided code snippet, where AWS X-Ray will measure the execution time of the code written between the 'segment.addNewSubsegment(…)' and 'subsegment.close()' functions. The custom subsegments will be displayed in the AWS X-Ray console under the Segment Timelines diagram.

How Can AWS X-Ray Help You Find Performance Bottlenecks?

Now that we know what AWS X-Ray has to offer and how to set it up, most of you will already have guessed how it can be a very useful tool but here are my favorite ways to take advantage of it:

Discovering Critical Services Under the Same Domain

AWS X-Ray provides (and builds based on the selected traces) a visual map of all the services linked to a specified domain.

In the example used above, we can see that this domain is composed of one API Gateway, four AWS Lambdas, and a single DynamoDB table.

Apart from seeing all the services linked to a domain, AWS X-Ray will also visually display the percentage of error executions that nodes might have.

In this provided example, we can easily see that the AppSync GraphQL API has an average error rate of around 10%.

Identifying the Performance Bottlenecks

Once the developer has found the nodes to be analyzed, the next step would be taking a look at the different traces for that node to better understand where it’s spending most of the execution time.

For this task, one could take advantage of the Segment Timelines. These timelines will visually display how long each action took to be executed.

From this example, we could see that the bottlenecks for the execution of this Lambda were:

1. The cold start, which added 733ms to the execution time.

2. The API request, which took 5.53s of the actual invocation time of the lambda.

After seeing these results, a developer would know that he would need to work possibly on avoiding cold starts and on improving (if owned) the API that is called during the execution.

Using Custom Subsegments to Profile & Improve Your Code

At last, one of the best-kept secrets of AWS X-Ray, using custom subsegments to profile your code and have a better understanding of where the time is spent during an execution.

Given this Segment Timeline, we would know that the execution is taking longer than it should since we expected the DynamoDB request to be the only time-consuming operation. Without the above traces, we wouldn’t be able to understand what is taking so long.

At this point, a developer would have two options:

1. Spend hours reviewing the code and blindly updating it to try to find the time-consuming task.

2. Add custom subsegments to the operations we suspect could be the culprit of the high execution time.

After adding a custom subsegment to the suspected function, we would be able to see a trace like this:

Here we can clearly see that the 'time-consuming operation' function is responsible for the extra 2.5 seconds of execution time. Thanks to this insight, the developer would know that they only need to focus on reviewing and improving that specific operation.

Conclusion

We highly recommend correctly setting up AWS X-Ray when developing services on AWS, especially if they are serverless, in order to allow for better observability and profiling. As showcased in this article, AWS X-Ray will allow developers to better understand how a service is performing and speed up the process of debugging performance bottlenecks or timeouts once the service is deployed to production.

Did you find this article interesting or useful? Do you have any questions or would like to chat more about it? I’d love to connect with you on my social media, you can find me on LinkedIn or Twitter.

References

• https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html

• https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html

This article provides an overview of the basics of AppSync APIs, including the recommended stack of Serverless Framework, Serverless AppSync Plugin, and GraphBolt. It explains the structure of resolvers, the use of ctx and stash objects, size limits for inline resolvers and resolvers uploaded to S3, and the use of variable substitutions for environment variables. It also covers how to refactor code and use it as a JS resolver for AppSync, and how to use GraphBolt for executing API requests and debugging resolvers.

Introduction

Getting started with AppSync APIs sounds like a daunting task, especially for developers used to developing REST APIs. There are a few new concepts that you'll need to learn and understand like the usage of data sources, Resolvers, Pipeline resolvers and how to set up a proper GraphQL schema.

In this article, we will expect that the basic knowledge is already covered, for example by heading to and reading the official documentation, and we will cover what we think will allow you to get started as fast as possible while still avoiding some common mistakes.

Why JavaScript Resolvers?

While developing AppSync APIs you have a few options to choose from to implement your logic, but we will focus on JavaScript resolvers since:

• They are the fastest way to get started

• Most of the developers will already have previous JS knowledge

As a little disclaimer, the JS resolvers are executed in a custom runtime called APPSYNC_JS where not all JS operations are supported, but we'll dive into it later.

Another option would be to go with VTL Mapping Template resolvers, but this would mean entering a rabbit hole that might be too overwhelming for developers trying to get started with AppSync.

Recommended Stack

With simplicity and future-proofness as our main goals, the stack to recommend would always be:

• Serverless Framework: My go-to IaC framework for developing serverless apps on AWS. This framework allows for an easy and fast declaration for every infrastructure or resource your project might need, and, for the ones that aren't as easy to set up, it allows for third-party plugins to make your life easier.

• Serverless AppSync Plugin: Plugin used to simplify the declaration and set up of your AppSync API.

• GraphBolt: The best tool I've been able to find so far to debug and test AppSync resolvers and APIs.

For an example of how to get started with both Serverless Framework and the Serverless AppSync Plugin, you can head to the project's readme quick start guide.

Basic Concepts

We won't go into much detail on the different concepts, but as a quick refresher of the basics:

• Data Sources: As the name implies, it is the reference to where the resolver will be fetching the data from.

• Resolvers: The connector between AppSync/GraphQL and the data source, aka. the file with the logic to be executed.

• Pipeline resolvers or functions: A set of resolvers to be executed in the predefined order to build the expected response.

Everything you need to know

Time to go right to the point, here are all the things I wish someone had explained to me before getting started and would have saved me a lot of time and headaches.

Resolver Structure: request(ctx) and response(ctx)

The most important thing to understand, and that you might already know, is the resolver structure. Resolvers tell AWS AppSync how to translate an incoming GraphQL request into instructions for your backend data source, and how to translate the response from that data source back into a GraphQL response.

Having this in mind, it starts to make sense that we're expected (and forced) to export two functions in our code:

• request(ctx): This will be the first function to be executed and should be used to verify the input and prepare or map the request parameters to be sent in the request made to the defined Data Source.

• response(ctx): This function will be called after the Data Source has been called and should be used to verify the received response and to map it to the expected schema needed for the response.

Everyone needs a bit of context

ctx, aka. context is what AppSync will provide when calling your resolver and it will contain all the information you might need to access during the execution of your resolver or pipeline.

The most relevant keys that you'll probably need are:

• ctx.args: A map that contains all GraphQL request arguments.

• ctx.stash: A stash is an object that lives throughout the whole execution of the resolver or pipeline. It can be used to pass information between request and response functions from a single resolver or between different resolvers in the same pipeline.

• ctx.result and ctx.error: These values will contain the result or errors from this resolver. One could for example access these keys from the response function to access the response provided by the Data Source.

• ctx.prev.result: Contains the value of the previous operation result. F.e.: the result of the response function from the previously executed resolver in a pipeline.

Not everything is allowed

And Appsyncs Safe word is "The code contains one or more errors". This is an error that you have probably already faced if you started developing JS resolvers like you were developing Lambdas.

JS Resolvers run in a custom runtime called APPSYNC_JS and is pretty limited regarding the operations that you will be able to perform inside the resolvers. To help developers avoid this kind of error, AWS provides an ESLint plugin that can be used to statically analyze your code to quickly find problems

Some of the non-allowed operations that you probably wanted to use are:

• async and await: These operations are not allowed, the only async/await operation that is allowed is the communication with the configured data source, which will be handled by AppSync.

• try - catch: You won't be able to use try-catch blocks, so make sure your code is top-notch and thoroughly tested.

• import and third-party dependencies: JS resolvers can't import or depend on any third-party dependency a part of @aws-appsync/utils which is already built into the custom runtime.

These are just a subset of the non-allowed operations to see the rest of them refer to the official documentation.

@aws-appsync/utils, your new best friend

This library will be the only one that you'll be able to import into your code, but don't worry about it, it contains most of the helper functions that you might need for your business logic.

The most relevant ones that you'll probably end up using are:

• util.error and util.appendError: helpers used to handle errors that you might want to throw/append to the response. util.error will throw an exception and break the execution and util.appendError will append the error and allow for the execution to continue.

• runtime.earlyReturn: This helper will break the execution of the current resolver and its input will be returned as the response. For example, calling runtime.earlyReturn({}); in the request function will avoid the response function from being executed, but it won't break the execution of the pipeline.

• util.dynamodb.toDynamoDB and util.dynamodb.toMapValues: helpers that convert input objects to the appropriate DynamoDB representation.

• util.time.*: A set of helper functions to ease the handling and creation of date times.

To see all of the provided operations you can check the official documentation.

Size Matters

Some people might say size doesn't matter but in this context, for JS resolvers, we have some size limits that we need to follow:

• 4,000 characters: This is the maximum size currently allowed for resolver code that is defined in-line in the cloud formation template. This will be your current limit if you're using the serverless-appsync-plugin but don't worry, there is a fix for that coming soon.

• 32,000 characters: In case use another IaC approach to the plugin and you're uploading the resolver code to S3, there is a higher allowed limit where you can use up to 32,000 characters per resolver.

Environment Variables, where are you?

For developers used to Lambdas, they might miss using Environment variables, especially if they change depending on the stage you deploy to.

AppSync/JS Resolvers don't currently support the use of environment variables but with the use of the serverless-appsync-plugin, you might take advantage of a feature called variable substitutions.

To use them you will just need to add a variable in your code with the following structure:

const tableName = '#myTable#';
return {
  operation: "BatchGetItem",
  tables: {
    [tableName]: { keys },
  },
};

The value assigned to the variables must be wrapped with # and the value in between should be the exact name used in your serverless.yml file, otherwise, it won't be updated during the deployment.

After setting the variable in your resolvers code, you will just need to add the substitution configuration on the serverless.yml file:

appSync:
  name: my-api
  substitutions: #global substitutions
    myTableName: !Ref myTable

  resolvers:
    Query.user:
      dataSource: my-table
      substitutions: #resolver substitutions
        myTableName: !Ref myTable

Refactoring is possible, you just need one extra step

As Benoît Bouré explained in his article a few months ago, it's possible to write reusable/refactor code and still use it as a JS resolver.

To take advantage of it you will need to consider a few things:

• AppSync only supports ES modules

• We will need to bundle the code before referencing it in our IaC

• We don't want to bundle the AppSync utils library

To bundle the code we would recommend you use the following command:

esbuild \
  --bundle \
  --target=esnext \
  --platform=node \
  --format=esm \
  --external:@aws-appsync/utils \
  --tree-shaking=true \
  --minify-whitespace \
  --minify-identifiers \
  --outdir=path/to/resolvers/build \
  path/to/resolvers/*.js

The previous command will bundle your code to the expected format to be referenced in your IaC.

We don't recommend using the --minify option since we found that the underlying --minify-syntax tends to introduce some unsupported operations. That's why we use --minify-whitespace and --minify-identifiers sepparately.

To automate this step, I would recommend you add the execution of the bundling as a new step to the deployment pipeline and always reference the resolvers from the build folder in your IaC.

A PR to remove this extra step is currently in the making, make sure to keep an eye on the plugins changelog to see if this step is still needed as of the time you're reading this.

No more headaches, use GraphBolt

Most of you will already be familiarized with Postman or any other tool that allows you to execute API requests and I know switching tools might be time-consuming, but you can think of GraphBolt as the Postman on steroids or the perfect AppSync companion.

The most relevant features that will help you save a lot of time and headaches are:

• GraphQL Client: A client that allows you to execute requests. Like Postman but tailored for AppSync, allowing for almost-automatic authentication handling, autocomplete and query formatting.

• Query Inspector: This allows you to go one step ahead of Postman but without the need of leaving the app. You will be able to: see all the recently executed queries, see the details of a single query (including the X-Ray traces, Cloudwatch logs and the executed resolvers) and even debug the execution of each resolver by accessing the Resolver details. This last option will allow you to see how every request/response function has been evaluated.

• Resolver Evaluation: As mentioned before, not everything is allowed in JS resolvers, and "The code contains one or more errors" is not useful at all. To streamline your development and find the issues easier you can use this function to test and evaluate the resolver code your building.

Conclusion

Getting started with AppSync and JS resolvers might seem like a daunting task, but by giving a quick read to the official documentation and having all the above-mentioned points in mind, you'll be up and running in no time developing AppSync GraphQL APIs.