GraphQL APIs with AppSync and DynamoDB
AWS AppSync moves the GraphQL server out of your own operational responsibility and into a managed service. Using a DynamoDB backend, I show when this build-vs-buy decision holds up and when managed becomes a dead end, including the VTL mapping templates that are the price for it in 2021.
If you publish a GraphQL schema, you have taken on running a server – even if the project plan only says “schema and clients”. The resolvers have to run somewhere, the connections have to end somewhere, the load has to be absorbed somewhere. That bill doesn’t arrive on deployment day; it arrives every month after.
The popular GraphQL introductions stop before this bill. Defining types, writing queries, fetching data with Apollo or urql: all well explained. The server with the resolvers, the database underneath, scaling, the real-time connections – they say nothing about those. Still, you can’t define this layer away. Someone builds it, deploys it and keeps it running.
That leaves the question of who this someone is: your own team or a managed service. I tie the answer to a concrete setup – AWS AppSync on DynamoDB, as it actually looks in mid-2021, including the VTL mapping templates that take some getting used to at first. The code isn’t the core here. The core is what this decision gains you and what it costs.
Editorial note (July 2026): Besides VTL, AppSync today supports the JavaScript-based resolver runtime APPSYNC_JS. VTL remains valid, but it is no longer the only direct mapping to DynamoDB. Managed takes running the GraphQL server off the team’s hands; schema, resolvers, permissions, data model, deployment and observability remain your own work.
What AppSync actually is#
AppSync is a fully managed GraphQL layer. The crucial point: you don’t run your own GraphQL server. There is no Node process with Apollo Server, no container, no hosting, no scaling logic you would have to take care of. Instead, you upload a schema in the GraphQL Schema Definition Language (SDL) and attach a resolver to each field that points to a data source. AWS handles the rest.
This shift is the real value. In a classic setup, the GraphQL server is the centerpiece that you write, deploy and run yourself. With AppSync, running that server lies with AWS, while the team describes the mapping between schema field and data source as well as its infrastructure. This is the familiar serverless trade: less operations of your own in exchange for tighter coupling to the service.
A resolver always connects exactly one schema field to a data source. And in 2021 there is a manageable but well-covered selection of those:
- DynamoDB tables as a key-value and document store
- AWS Lambda for any custom logic
- HTTP endpoints to connect existing REST APIs
- Amazon Elasticsearch Service for full-text search
- relational databases via RDS or Aurora Serverless, plus “None” local resolvers without an external source
In this post I focus on DynamoDB, because it is the most common combination in serverless projects and because it shows the VTL mechanics best.
The request flow#
Before we look at code, it helps to look at the path a request takes. A client sends a GraphQL query or mutation to AppSync. AppSync validates it against the schema and calls the matching resolver for the requested field. The resolver has two parts: a request template that translates the GraphQL request into a DynamoDB call, and a response template that turns the DynamoDB result back into GraphQL form.
flowchart LR Client[GraphQL Client] -->|Query / Mutation| AppSync[AppSync<br/>Schema + VTL Resolver] AppSync -->|Request Template| DDB[(DynamoDB Table)] DDB -->|Response Template| AppSync AppSync -->|JSON Result| Client AppSync -.->|other data sources| Lambda[AWS Lambda] AppSync -.->|other data sources| HTTP[HTTP Endpoint]
These two templates are the centerpiece and, at the same time, the part where opinions split in 2021. That’s because they are not written in JavaScript but in the Apache Velocity Template Language, VTL for short.
VTL: the language in between#
VTL is a template language, not a full programming language. It can insert values and express simple conditions and loops, but it is deliberately kept narrow. For translating between GraphQL arguments and DynamoDB calls, that is enough in most cases, and AWS ships a set of helper functions that take care of the typical tasks.
Let’s take a small CMS as an example. We want to create blog posts, fetch them individually and be notified in real time about new posts. The schema looks like this:
type Post {
id: ID!
title: String!
body: String!
}
type Query {
getPost(id: ID!): Post
}
type Mutation {
createPost(title: String!, body: String!): Post
}
type Subscription {
onCreatePost: Post @aws_subscribe(mutations: ["createPost"])
}
This is plain SDL, as you know it from any GraphQL introduction. The only AppSync-specific addition is the @aws_subscribe directive on the subscription field, more on that later. First, the resolvers for createPost and getPost.
A PutItem resolver#
When a client calls createPost, a new item should land in the DynamoDB table. The request template describes exactly this PutItem call:
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"id": $util.dynamodb.toDynamoDBJson($util.autoId())
},
"attributeValues": $util.dynamodb.toMapValues($ctx.args)
}
A lot happens in a small space here. The version string "2017-02-28" sets the template format. In 2021 that’s the default value you don’t change without a specific reason. The operation field tells DynamoDB what to do. The key is created via $util.autoId(), a helper function that generates a UUID so that each post gets a unique primary key.
The most important point hides in $util.dynamodb.toDynamoDBJson(...) and $util.dynamodb.toMapValues(...). DynamoDB doesn’t expect values as bare strings or numbers but in a typed attribute format: a string becomes {"S": "..."}, a number {"N": "..."}. These helper functions handle the conversion automatically. If you forget them and insert the raw values directly, you write an item in the wrong format – the mistake almost everyone stumbles over once when getting started with AppSync.
The response template, by contrast, is unspectacular. It simply returns the written item as JSON:
$util.toJson($ctx.result)
$ctx, also available as $context, is the object that gives you access to everything relevant: $ctx.args for the arguments of the GraphQL operation, $ctx.identity for information about the calling user, $ctx.result for the result of the data source. The response template uses $ctx.result to send the item that was just written back to the client.
Besides the plain result, AppSync also provides $ctx.error in the response template in case the data source returns an error, such as a rejected condition on a PutItem. If you ignore it, you silently return null on failure instead of giving the client a meaningful message. With $util.error(...) or $util.appendError(...) you can pass the error through to the GraphQL response in a controlled way, so that it ends up in the errors block of the response. For the two simple resolvers here, you can still do without it, but as soon as real conditions come into play, this check belongs in the template.
A GetItem resolver#
For getPost, things are even simpler. The request template describes a GetItem call with the id argument as the key:
{
"version": "2017-02-28",
"operation": "GetItem",
"key": {
"id": $util.dynamodb.toDynamoDBJson($ctx.args.id)
}
}
Here, too, the value from $ctx.args.id goes through toDynamoDBJson so that it arrives at DynamoDB in the right format. The response template is identical to the previous one:
$util.toJson($ctx.result)
When you put these two resolvers side by side, the principle becomes tangible: a resolver is always a pair of request and response template that connects a schema field to a concrete DynamoDB operation. There is no more magic behind it.
The available operations cover the usual DynamoDB repertoire. Besides GetItem and PutItem, there are UpdateItem and DeleteItem, plus Query and Scan for multiple results as well as the batch and transaction variants such as BatchGetItem or TransactWriteItems. The four single-item operations are enough to get started, and you grow into the more complex variants along with the data model. The nice thing is that the pattern always stays the same. You change the operation field, adjust key and values, and the structure of the template barely changes. This uniformity is what makes VTL manageable in daily work despite its clunkiness.
Subscriptions with no effort of your own#
The part that surprises people most at first contact is the real-time subscriptions. In a self-built GraphQL server, this is the most laborious part of all: managing WebSocket connections, running a pub/sub system, keeping state in sync across several server instances. With AppSync, you have to do none of that.
Let’s recall the directive from the schema:
type Subscription {
onCreatePost: Post @aws_subscribe(mutations: ["createPost"])
}
This one line is enough. @aws_subscribe(mutations: ["createPost"]) binds the subscription field onCreatePost to the createPost mutation. Whenever this mutation completes successfully, AppSync pushes the result over a WebSocket connection to all clients that have subscribed to onCreatePost. No polling, no server of your own, no connection management.
sequenceDiagram participant A as Client A participant AS as AppSync participant D as DynamoDB participant B as Client B (subscribed) A->>AS: mutation createPost AS->>D: PutItem D-->>AS: written item AS-->>A: created Post AS-->>B: onCreatePost (WebSocket push)
The connection runs over WebSockets, which AppSync provides out of the box. The client only has to subscribe to onCreatePost once and then automatically receives every new post. For a live feed, a chat feature or a dashboard, this is a huge simplification, because the entire real-time part disappears from your own operational responsibility.
One detail you must not overlook: without the @aws_subscribe directive, simply nothing happens. More than once I have seen someone define a subscription, connect the client and then wonder why no events arrive. The answer was the same every time: the directive was missing or pointed to the wrong mutation. The subscription field has to be coupled explicitly to the mutation that triggers it.
Where VTL reaches its limits#
As elegant as the approach is, its edges are just as clear. VTL is deliberately not a programming language, and you notice that as soon as the logic gets more complex. Nested conditions, multi-step transformations, merging several sources: you can express all of this in VTL somehow, but the templates quickly become unreadable and hard to maintain.
The limit lies where a template does more than reorder arguments and pour them into a DynamoDB call. As of 2021, more complex logic belonged in a Lambda resolver. Today you should first check whether an APPSYNC_JS resolver expresses the mapping more readably; for free-form runtime logic and external libraries, Lambda remains the further-reaching option. VTL is still well suited for lean, direct mappings to DynamoDB.
The second edge doesn’t concern AppSync but DynamoDB itself. Whether an access becomes a Query or a Scan is decided by the table design. A Query uses partition and sort key or a global secondary index and is fast and cheap. A Scan reads the whole table if in doubt and becomes expensive and slow as the data grows. You have to think through these access patterns before the first write, because DynamoDB rarely forgives a poorly planned key design after the fact. The nice AppSync frontend doesn’t change the fact that underneath sits a DynamoDB table with its own rules.
Managed or self-hosted: the real decision#
So far it has been about mechanics. The reason I bring up AppSync in projects at all lies one level higher. A GraphQL server is not a feature you write once and then forget. It is a permanent operational commitment. It has to run, scale, be updated and be monitored, and with real-time connections, all the state across several instances comes on top. These costs don’t arise once during the build but every month in operation.
At this point, build vs. buy means concretely: running it yourself means a Node process with Apollo Server, hosting, a scaling strategy, a pub/sub system for subscriptions and the willingness to fix all of it at night when things go wrong. Managed means that I declare schema, resolvers and data sources and hand the rest over to AWS. I then no longer pay in operating hours but in usage and in a piece of control that I give away.
When does managed hold up? Whenever the GraphQL server is not a differentiator for the product but a necessity. A CRUD backend with a real-time feed is rarely the part with which a team stands out from the competition. Exactly such standard layers are better bought in, because every self-operated hour is missing where the team actually creates value. Small teams without their own platform team, projects with fluctuating load, prototypes that have to go live quickly: in all these cases, dropping the operations is worth more than the control you give up.
When does managed become a dead end? As soon as the mapping the service offers no longer fits your own problem. For AppSync in 2021, VTL is this mapping. As long as I pour arguments into DynamoDB calls, it’s a good trade. As soon as I squeeze nested logic, multi-step transformations or merging several sources into templates, I pay back the managed convenience with maintainability. The second dead-end marker is lock-in. Schema and clients stay portable; the VTL resolvers and the DynamoDB key design don’t. If you expect to switch providers later, you should keep this boundary layer deliberately thin.
This boils the decision down to a few criteria. Is the layer standard or differentiation? How expensive are operations relative to team size? How well does the offered mapping fit your own problem, today and in two years? And how deep does the lock-in go if the answer no longer fits one day? Managed is not a matter of faith but a calculation you redo for each layer. For AppSync, it clearly comes out in favor of buy for a large share of serverless projects, but not for all of them.
What remains in the end#
I’ll come back to the beginning, to the question of running the server. The popular GraphQL content covers schema design and the client side. That is important and stays important, no matter which backend sits underneath. AppSync with DynamoDB is the other half, the managed backend, where the self-written server melts down into a configuration of schema, resolvers and data sources.
The effect of this decision is concrete: the team still deploys schema, resolvers and infrastructure, but doesn’t run its own GraphQL process or its own WebSocket layer. This leaves more time for the data model and domain logic. Whether the calculation works out depends on how well the resolver runtimes and data sources fit the problem.
The price for this is the VTL templates and a degree of lock-in to AWS. Both are manageable as long as you know the limits: lean mappings in VTL, complex logic in Lambda, a key design that anticipates the access patterns. Where these limits hold, the trade is excellent. Where they break, the layer should be built yourself. Drawing this line cleanly is the real architecture work, not writing the templates.
AppSync doesn’t stand on its own. It meshes with Lambda, DynamoDB and the other managed services, and it unfolds its value precisely in this interplay.
Further reading#
- Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html
- Repository with the schema and resolver examples from my serverless workshops
- DynamoDB resolver reference (AWS)
APPSYNC_JSresolver reference (AWS)- Tutorial: Simple Post Application with DynamoDB resolvers (AWS)
- Resolver mapping template overview (AWS)
- $util utility reference (AWS)
- AppSync FAQs on data sources and subscriptions (AWS)
Revised and translated from German with the help of AI.