AWS AppSync: Real-Time GraphQL APIs and Offline Data Sync

You've built a real-time dashboard. Users love it—until the WebSocket server crashes during a demo, taking down all active connections. That's the moment you realize managing real-time infrastructure at scale is a nightmare. AWS AppSync solves this by providing a managed GraphQL endpoint with built-in WebSocket support, automatic conflict resolution, and offline data sync. It's not just a GraphQL server; it's a state management platform that handles the hard parts of distributed data synchronization. If you're tired of stitching together Lambda, API Gateway, DynamoDB Streams, and custom WebSocket logic, AppSync is your escape hatch. But be warned: it comes with its own set of sharp edges, like complex resolver mapping templates and unexpected costs from data transfer. This article cuts through the hype and shows you how to use AppSync in production without shooting yourself in the foot.

Why Real-Time GraphQL Matters in Production

Real-time data is no longer a nice-to-have; it's a requirement for modern applications like collaborative editing, live dashboards, and chat systems. AWS AppSync provides managed GraphQL with built-in real-time subscriptions and offline data sync, eliminating the need to cobble together WebSocket servers and conflict resolution logic. In production, the key advantage is reduced operational overhead: AppSync handles connection management, scaling, and data synchronization out of the box. However, real-time systems introduce complexity around data consistency, latency, and cost. This article focuses on building a production-grade real-time API with AppSync, covering subscriptions, offline sync, conflict resolution, and monitoring. We assume you're already familiar with GraphQL basics and AWS services like DynamoDB and Lambda.

type Todo {
  id: ID!
  title: String!
  completed: Boolean!
  version: Int!
}

type Mutation {
  updateTodo(id: ID!, title: String, completed: Boolean, expectedVersion: Int!): Todo
}

type Subscription {
  onUpdateTodo(id: ID!): Todo
    @aws_subscribe(mutations: ["updateTodo"])
}

type Query {
  getTodo(id: ID!): Todo
  listTodos: [Todo]
}

Configuring Real-Time Subscriptions with AppSync

AppSync subscriptions are triggered by mutations. When a mutation completes, AppSync publishes the result to all connected clients subscribed to that mutation. In production, you need to consider authorization: subscriptions can be filtered by arguments (e.g., only receive updates for a specific todo ID). This reduces bandwidth and processing on the client. To set up a subscription, define it in the schema with the @aws_subscribe directive, specifying which mutations trigger it. On the client, use the AWS AppSync SDK to subscribe. The SDK handles reconnection and backoff automatically. However, you must handle stale subscriptions when the client's auth token expires. Implement token refresh logic in the subscription handler to avoid silent disconnections.

import { API, graphqlOperation } from 'aws-amplify';
import { onUpdateTodo } from './graphql/subscriptions';

const subscription = API.graphql(
  graphqlOperation(onUpdateTodo, { id: '123' })
).subscribe({
  next: (data) => {
    console.log('Todo updated:', data.value.data.onUpdateTodo);
    // Update local state
  },
  error: (error) => {
    console.error('Subscription error:', error);
    // Reconnect logic
  }
});

// Cleanup on unmount
subscription.unsubscribe();

Implementing Offline Data Sync with Conflict Resolution

Offline sync allows users to continue working without connectivity. AppSync's DataStore library handles local storage, queueing mutations, and syncing when online. The critical piece is conflict resolution: when two clients modify the same record offline, AppSync uses a conflict detection mechanism. The default is 'optimistic concurrency' using a version field. When a mutation is applied, the client sends the expected version. If the server's version is higher, the mutation fails, and the client must reconcile. You can implement custom conflict resolution via a Lambda function. In production, always use version-based detection. Avoid 'last writer wins' as it causes data loss. Test conflict scenarios thoroughly, especially with long offline periods.

// Custom conflict resolver Lambda
const AWS = require('aws-sdk');
const docClient = new AWS.DynamoDB.DocumentClient();

exports.handler = async (event) => {
  const { payload, existing } = event;
  // payload: incoming mutation arguments
  // existing: current item in DynamoDB
  
  // Auto-merge: take the latest version of each field
  const merged = {
    ...existing,
    ...payload,
    version: existing.version + 1
  };
  
  return {
    item: merged,
    conflictResolution: 'MERGE'
  };
};

Handling Large Payloads and Connection Limits

AppSync has limits: maximum payload size is 4 MB for requests and responses, and each WebSocket connection can have up to 100 active subscriptions. In production, you may need to handle large payloads (e.g., file uploads) or many subscriptions per client. For large payloads, use S3 presigned URLs and store references in GraphQL. For many subscriptions, consider batching updates or using a single subscription with a filter. Also, monitor connection limits: AppSync allows up to 2,000 concurrent connections per API by default (can be increased). If you exceed this, clients will fail to connect. Implement exponential backoff on the client and set up CloudWatch alarms for connection count.

// Subscribe to all updates with a filter
const subscription = API.graphql(
  graphqlOperation(onUpdateTodo, { id: null }) // null means all
).subscribe({
  next: (data) => {
    const todo = data.value.data.onUpdateTodo;
    if (todo.userId === currentUser.id) {
      // Process only relevant updates
    }
  }
});

Monitoring and Debugging Real-Time APIs

Production monitoring for AppSync involves CloudWatch metrics (latency, errors, connection count) and logging (request/response logs). Enable detailed logging for mutations and subscriptions to debug issues. Use X-Ray tracing to visualize end-to-end requests. Common issues: subscription failures due to auth token expiry, high latency from slow resolvers, and throttling from DynamoDB. Set up CloudWatch alarms for error rate > 1% and connection count > 80% of limit. For debugging, use the AppSync console's Queries tab to test subscriptions. Also, log subscription lifecycle events on the client (connected, disconnected, error) to detect network issues.

// Client-side subscription lifecycle logging
const subscription = API.graphql(
  graphqlOperation(onUpdateTodo, { id: '123' })
).subscribe({
  next: (data) => { /* ... */ },
  error: (error) => {
    console.error('Subscription error:', error);
    // Log to CloudWatch via API
  },
  complete: () => {
    console.log('Subscription completed');
  }
});

// Also listen for connection state
Hub.listen('api', (data) => {
  const { payload } = data;
  if (payload.event === 'ConnectionStateChange') {
    console.log('Connection state:', payload.connectionState);
  }
});

Scaling Real-Time Subscriptions with AppSync

As your user base grows, you need to scale subscriptions. AppSync automatically scales WebSocket connections across multiple nodes, but there are bottlenecks: each subscription is tied to a single mutation resolver. If you have many clients subscribing to the same mutation, the resolver is called once per mutation, and the result is broadcast to all subscribers. This is efficient. However, if you have many distinct subscriptions (e.g., per-user), the number of subscriptions can become large. Use subscription filtering to reduce the number of subscriptions. For high-throughput scenarios, consider using a fan-out pattern with SNS or Kinesis to trigger mutations in batches. Also, use DynamoDB streams to trigger mutations for bulk updates.

// Lambda triggered by DynamoDB Stream to fan-out updates
const AWS = require('aws-sdk');
const appsync = new AWS.AppSync({ region: 'us-east-1' });

exports.handler = async (event) => {
  for (const record of event.Records) {
    if (record.eventName === 'MODIFY') {
      const todo = AWS.DynamoDB.Converter.unmarshall(record.dynamodb.NewImage);
      // Call AppSync mutation to trigger subscription
      await appsync.graphql({
        apiId: process.env.API_ID,
        query: `mutation { updateTodo(id: "${todo.id}", title: "${todo.title}", completed: ${todo.completed}, expectedVersion: ${todo.version}) { id } }`
      }).promise();
    }
  }
};

Security Best Practices for Real-Time APIs

Security for real-time APIs involves authentication, authorization, and data validation. Use AWS Cognito for user pools and federated identities. For subscriptions, enforce authorization at the resolver level using @aws_auth or custom resolvers that check the caller's identity. Never expose sensitive data in subscription payloads. Use field-level authorization to restrict access. Also, validate input in mutations to prevent injection attacks. For offline sync, ensure that local data is encrypted at rest on the device. Use AWS AppSync's built-in support for AWS WAF to protect against DDoS attacks. Regularly rotate API keys if using API key auth (not recommended for production).

type Todo @aws_auth(cognito_groups: ["Admin"]) {
  id: ID!
  title: String!
  completed: Boolean!
  owner: String
}

type Mutation {
  updateTodo(id: ID!, title: String, completed: Boolean, expectedVersion: Int!): Todo
    @aws_auth(cognito_groups: ["User"])
}

type Subscription {
  onUpdateTodo(id: ID!): Todo
    @aws_subscribe(mutations: ["updateTodo"])
    @aws_auth(cognito_groups: ["User"])
}

Cost Optimization for Real-Time APIs

AppSync pricing is based on query and mutation requests, plus data transfer for subscriptions. Real-time subscriptions incur charges per message delivered. To optimize costs: reduce subscription payload size by selecting only needed fields, use subscription filtering to avoid broadcasting to all clients, and batch mutations when possible. For offline sync, minimize the number of sync queries by using delta sync (only fetch changed records). Monitor usage with Cost Explorer and set budgets. Consider using a caching layer (e.g., DynamoDB Accelerator) to reduce read costs. Also, use reserved capacity for DynamoDB if you have predictable traffic.

// Client-side delta sync
import { DataStore } from 'aws-amplify';
import { Todo } from './models';

async function syncTodos() {
  const lastSync = localStorage.getItem('lastSyncTime');
  const models = await DataStore.query(Todo, (c) => 
    c.updatedAt('gt', new Date(parseInt(lastSync)))
  );
  localStorage.setItem('lastSyncTime', Date.now().toString());
  return models;
}

Testing Real-Time and Offline Behavior

Testing real-time and offline features requires specialized approaches. Use integration tests with a real AppSync API and DynamoDB table. For offline testing, simulate network failures using tools like Charles Proxy or browser dev tools. Write unit tests for conflict resolution logic. For subscriptions, test that mutations trigger the correct subscription events. Use the AppSync console to manually test subscriptions. Automate tests with AWS SDK to call mutations and verify subscription delivery via WebSocket. Also, test edge cases: concurrent mutations, long offline periods, and reconnection storms.

const AWS = require('aws-sdk');
const appsync = new AWS.AppSync({ region: 'us-east-1' });
const { createWebSocket } = require('graphql-ws');

async function testSubscription() {
  // Create WebSocket connection
  const ws = createWebSocket({
    url: 'wss://your-api.appsync-realtime-api.us-east-1.amazonaws.com/graphql',
    connectionParams: { auth: { ... } }
  });
  
  // Subscribe
  ws.subscribe({
    query: `subscription { onUpdateTodo(id: "123") { id title } }`,
    next: (data) => {
      console.log('Received:', data);
      // Assert expected data
    }
  });
  
  // Trigger mutation
  await appsync.graphql({
    apiId: 'your-api-id',
    query: `mutation { updateTodo(id: "123", title: "test", completed: false, expectedVersion: 1) { id } }`
  }).promise();
}

Production Deployment and Rollback Strategies

Deploying AppSync changes requires careful planning. Use Infrastructure as Code (e.g., AWS CDK, Terraform) to manage schema, resolvers, and data sources. Implement canary deployments by creating a new API endpoint and gradually shifting traffic. For schema changes, avoid breaking changes: add fields instead of removing them, and deprecate fields before removal. Use versioning for your API (e.g., v1, v2) if breaking changes are unavoidable. For rollbacks, keep previous schema versions in source control and use CloudFormation stack rollback. Monitor deployment with CloudWatch alarms. Also, test offline clients with the new schema to ensure backward compatibility.

import * as appsync from '@aws-cdk/aws-appsync';
import * as dynamodb from '@aws-cdk/aws-dynamodb';

const api = new appsync.GraphqlApi(this, 'TodoApi', {
  name: 'todo-api',
  schema: appsync.Schema.fromAsset('schema.graphql'),
  authorizationConfig: {
    defaultAuthorization: {
      authorizationType: appsync.AuthorizationType.USER_POOL,
      userPoolConfig: { userPool: myUserPool }
    }
  }
});

const table = new dynamodb.Table(this, 'TodoTable', { ... });
api.addDynamoDbDataSource('TodoDataSource', table);