Build a GraphQL API with AWS AppSync

By Kokil Thapa | Last reviewed: August 2026

If you need to ship a managed GraphQL backend without maintaining EC2 instances or Apollo servers, you should build a GraphQL API with AWS AppSync. AppSync handles caching, real-time subscriptions, and multi-source data fetching natively, making it ideal for mobile apps and SPAs where latency matters. For developers accustomed to traditional REST architectures in frameworks like Laravel, the shift requires understanding resolver mapping templates rather than controller logic. This guide covers the production-critical configuration steps often missing from basic tutorials.

Transitioning from synchronous PHP/MySQL patterns to event-driven cloud APIs changes how you structure data access. While I spend most of my time shipping Laravel API best practices for legal-tech and eCommerce clients, AppSync solves specific scaling problems that monolithic frameworks struggle with—particularly when serving global mobile users or requiring offline-first synchronization. The trade-off is operational complexity in resolver debugging and vendor-specific tooling.

How do you design an AppSync schema for DynamoDB?

The most common failure point when engineers first build a GraphQL API with AWS AppSync is treating DynamoDB like a relational database. You cannot perform arbitrary joins or complex WHERE clauses efficiently. Your schema must reflect your access patterns, not your entity relationships. In practice, this means denormalizing data at write time so reads are single-item fetches or simple queries against Global Secondary Indexes (GSIs).

Define access patterns before writing SDL

List every query your frontend needs. For a legal case management portal, you might need "cases by client," "documents by case," and "appointments by attorney." Each becomes either a primary key lookup or a dedicated GSI. If a query doesn't map cleanly to one, redesign the table or accept that you'll need a Lambda resolver instead of direct DynamoDB access.

Use composite keys for hierarchical data

DynamoDB excels when you model parent-child relationships in a single partition. Use a partition key like CASE#caseId and sort keys prefixed with entity type: DOC#docId, TASK#taskId. This lets you fetch a case and all its related items in a single Query operation, which is far cheaper than multiple GetItem calls or application-side joins.

<!-- Example VTL request template for hierarchical query -->
{
  "version": "2018-05-29",
  "operation": "Query",
  "query": {
    "expression": "pk = :pk AND begins_with(sk, :prefix)",
    "expressionValues": {
      ":pk": $util.dynamodb.toDynamoDBJson("CASE#$ctx.args.caseId"),
      ":prefix": $util.dynamodb.toDynamoDBJson("DOC#")
    }
  }
}

Avoid nested resolvers for list fields

A common mistake is defining a Case.documents field with its own resolver that fires once per case in a list response. With 50 cases, that's 51 DynamoDB calls. Instead, use batch operations (BatchGetItem) or denormalize document summaries into the case item itself. Reserve nested resolvers only for detail views where the user explicitly requests expanded data.

What is the difference between VTL and JavaScript resolvers in 2026?

When you build a GraphQL API with AWS AppSync today, you have two resolver runtime options. Velocity Template Language (VTL) has been the default since launch, but AWS now recommends JavaScript resolvers for new projects. Both execute in the AppSync service layer—not in Lambda—and both compile to optimized evaluation plans. The choice affects developer experience, debugging capability, and long-term maintenance.

In my experience working on production serverless backends, JavaScript resolvers reduce cognitive load significantly. You can write familiar array methods, conditionals, and error handling instead of wrestling with VTL's whitespace-sensitive templating syntax. However, VTL remains relevant for existing deployments and ultra-simple pass-through mappings where JavaScript's overhead isn't justified.

Migrating from VTL to JavaScript incrementally

You don't need to rewrite everything at once. AppSync allows mixing runtimes per field. Start with new features in JavaScript, then migrate high-churn VTL resolvers during refactors. Test each migration against captured production requests using the AppSync console's test harness before deploying.

How do you implement secure authorization in AppSync?

Security configuration is where most AppSync projects fail audit. Unlike traditional REST APIs protected by middleware, AppSync supports four authorization modes simultaneously: API Key, IAM, Amazon Cognito User Pools, and OpenID Connect. Choosing correctly depends on your consumer profile. For client-facing applications serving authenticated users, Cognito User Pools should be your default. For backend-to-backend communication or CI/CD pipelines, use IAM signatures. Never use API Keys beyond prototyping—they lack identity context and expire after seven days unless rotated manually.

Implement row-level security in resolvers

Never trust the client to filter data. Even if your frontend only shows "my cases," a malicious actor can modify the query. In every resolver, validate ownership against $ctx.identity.username or group membership. For DynamoDB, bake the user ID into the partition key so unauthorized queries return empty results rather than throwing errors—which leak information about record existence.

// JavaScript resolver enforcing ownership
export function request(ctx) {
  const userId = ctx.identity.username;
  if (ctx.args.owner !== userId) {
    util.unauthorized();
  }
  return {
    operation: 'GetItem',
    key: {
      pk: util.dynamodb.toString(`USER#${userId}`),
      sk: util.dynamodb.toString(`CASE#${ctx.args.caseId}`)
    }
  };
}

Handle multi-auth scenarios gracefully

Many production systems serve both end-users (Cognito) and internal services (IAM). Define a default authorization mode at the API level, then override per-field using directives like @aws_iam or @aws_cognito_user_pools. Document these overrides clearly—mixing auth modes without explicit annotations leads to silent failures where legitimate requests get rejected because they hit the wrong default provider.

How do you enable real-time subscriptions in AppSync?

Real-time capabilities are a primary reason teams choose to build a GraphQL API with AWS AppSync over self-managed alternatives. Subscriptions use MQTT over WebSocket under the hood, managed entirely by AWS. You declare subscription operations in your schema tied to mutation names, and AppSync routes published events to connected clients automatically. No socket servers, no Redis pub/sub configuration, no connection state management.

Tie subscriptions to mutations explicitly

Subscriptions don't listen to tables—they listen to mutation invocations. When you define onCreateCase, AppSync publishes the mutation's return value to subscribers immediately after the mutation succeeds. If you bypass AppSync mutations (e.g., writing directly to DynamoDB via Lambda), no subscription fires. This coupling is intentional: it guarantees consistency between what was written and what was broadcast.

type Subscription {
  onCreateCase(owner: String!): Case
    @aws_subscribe(mutations: ["createCase"])
  
  onUpdateDocument(caseId: ID!, docType: String): Document
    @aws_subscribe(mutations: ["updateDocument"])
}

Filter subscriptions server-side

Client-side filtering wastes bandwidth and exposes sensitive metadata. Use subscription arguments to narrow the stream before it leaves AWS. A client subscribing to onUpdateDocument(caseId: "123") receives only updates for that case. Combine this with resolver-level authorization to ensure users can't subscribe to resources they shouldn't access—even if they guess valid IDs.

Manage connection lifecycle in production

WebSocket connections drop due to network changes, app backgrounding, or timeouts. Implement exponential backoff reconnection in your client SDK. On the server side, monitor Connect and Disconnect metrics in CloudWatch to detect abnormal churn rates. High disconnect frequency often indicates overly aggressive timeout settings or unhandled authentication token refresh cycles. For Nepal-based users on variable mobile networks, increase heartbeat intervals to prevent unnecessary reconnect storms.

When should you avoid AppSync for GraphQL?

Despite its strengths, AppSync isn't universal. Understanding its limits prevents costly rewrites later. If your workload involves heavy server-side computation, complex transactions across multiple tables, or deep integration with non-AWS ecosystems, evaluate alternatives carefully. For teams already running serverless Laravel on AWS Lambda, adding AppSync introduces a second paradigm that may not justify the operational split.

• Complex relational queries: If you need JOINs, aggregations, or window functions, put Aurora Serverless behind a Lambda resolver—or stick with PostgreSQL and a traditional GraphQL server like Hasura or PostGraphile.
• Vendor portability requirements: AppSync's resolver templates and subscription model are AWS-specific. Migrating away requires rewriting every resolver. If multi-cloud is a hard requirement, use an open-source framework deployed on ECS/Kubernetes.
• High-frequency polling patterns: Subscriptions excel at push, but if your clients poll every few seconds regardless of changes, REST with HTTP caching or tRPC may be simpler and cheaper.
• Team unfamiliarity with VTL/JS resolvers: The learning curve is real. Budget 2–4 weeks for developers to become productive. If timelines are tight and GraphQL isn't mandatory, REST with well-documented OpenAPI specs ships faster.

For Nepal-based startups evaluating costs, remember that AppSync charges per query/mutation plus data transfer. At low volumes, it's economical (~NPR 500–1,000/month for light usage). But at high query rates without aggressive caching, bills escalate faster than provisioned EC2. Always model expected costs using the AWS Pricing Calculator before committing.

Build a GraphQL API with AWS AppSync for Production

Shipping a reliable AppSync API requires discipline beyond the getting-started tutorial. Design your DynamoDB schema around access patterns, enforce authorization in every resolver, prefer JavaScript resolvers for new work, and treat subscriptions as mutation-coupled streams—not generic event buses. Monitor CloudWatch metrics for latency spikes and subscription churn. Start small with a single domain boundary, validate the pattern, then expand. If you're evaluating whether AppSync fits your next project or need help migrating an existing GraphQL workload, reach out to discuss your architecture.