localstack · cloutierMat · Jul 14, 2025 · Jul 14, 2025 · Jul 14, 2025 · Jul 30, 2025
@@ -8,20 +8,36 @@ import FeatureCoverage from "../../../../components/feature-coverage/FeatureCove
 
 ## Introduction
 
-AppSync is a managed service provided by Amazon Web Services (AWS) that enables you to create serverless GraphQL APIs to query databases, microservices, and other APIs.
-AppSync allows you to define your data models and business logic using a declarative approach, and connect to various data sources, including other AWS services, relational databases, and custom data sources.
+AWS AppSync is a fully managed API management service that connects applications to events, data, and AI models.
 
 LocalStack allows you to use the AppSync APIs in your local environment to connect your applications and services to data and events.
 The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of AppSync's integration with LocalStack.
 
-## Getting started
+## Getting Started
+
+This guide is designed for users new to **AppSync** in LocalStack, and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script.
+
+LocalStack supports two primary ways to work with AppSync:
+
+* **GraphQL**: use schemas and resolvers to interact with data sources like DynamoDB.
+* **Events API**: enable sending real-time event data to subscribed clients.
+
+Start your LocalStack container using your preferred method, then jump into the section that matches your use case:
+
+* [GraphQL API](#graphql-api): build query-based APIs with schema-first design.
+* [Events API](#events-api): build with publish/subscribe style, real-time messaging.
+
+### GraphQL API
+
+Create serverless GraphQL APIs to query databases, microservices, and other APIs.
+AppSync allows you to define your data models and business logic using a declarative approach, and connect to various data sources, including other AWS services, relational databases, and custom data sources.
 
 This guide is designed for users new to AppSync and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script.
 
 Start your LocalStack container using your preferred method.
 We will demonstrate how to create an AppSync API with a DynamoDB data source using the AWS CLI.
 
-### Create a DynamoDB table
+#### 1. Create a DynamoDB table
 
 You can create a DynamoDB table using the [`CreateTable`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html) API.
 Execute the following command to create a table named `DynamoDBNotesTable` with a primary key named `NoteId`:
@@ -49,7 +65,7 @@ awslocal dynamodb list-tables
 }
 ```
 
-### Create a GraphQL API
+#### 2. Create a GraphQL API
 
 You can create a GraphQL API using the [`CreateGraphqlApi`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateGraphqlApi.html) API.
 Execute the following command to create a GraphQL API named `NotesApi`:
@@ -94,7 +110,7 @@ awslocal appsync create-api-key \
 }
 ```
 
-### Create a GraphQL schema
+#### 3. Create a GraphQL schema
 
 Create a file named `schema.graphql` with the following content:
 
@@ -137,7 +153,7 @@ awslocal appsync start-schema-creation \
 }
 ```
 
-### Create a data source
+#### 4. Create a data source
 
 You can create a data source using the [`CreateDataSource`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateDataSource.html) API.
 Execute the following command to create a data source named `DynamoDBNotesTable`:
@@ -164,7 +180,7 @@ awslocal appsync create-data-source \
 }
 ```
 
-### Create a resolver
+#### 5. Create a resolver
 
 You can create a resolver using the [`CreateResolver`](https://github.com/localstack/docs/pull/782) API.
 You can create a custom `request-mapping-template.vtl` and `response-mapping-template.vtl` file to use as a mapping template to use for requests and responses respectively.
@@ -180,10 +196,201 @@ awslocal appsync create-resolver \
     --response-mapping-template file://response-mapping-template.vtl
 ```
 
-## Custom GraphQL API IDs
+### Events API
+
+Create a fully managed WebSocket API that lets you subscribe to channels and broadcast events to subscribers.
+
+#### 1. Create an Events API
+
+You can create an Events API using the [CreateApi](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateApi.html) API. The following command will create an Events API with the name `my-api`. 
+Note the `apiId`, `dns.REALTIME` and `dns.HTTP` in the outputs as it will be reused as `<api-id>`, `<realtime-domain>` and `<http-domain>` for the remainder of this example.
+
+```bash
+awslocal appsync create-api \
+    --name my-api \
+    --event-config '{
+        "authProviders":[{"authType": "API_KEY"}],
+        "connectionAuthModes":[{"authType": "API_KEY"}],
+        "defaultSubscribeAuthModes":[{"authType": "API_KEY"}],
+        "defaultPublishAuthModes":[{"authType": "API_KEY"}]
+    }'
+```
+
+```bash title="Output"
+{
+    "api": {
+        "apiId": "<api-id>",
+        "name": "my-api",
+        "tags": {},
+        "dns": {
+            "REALTIME": "<endpoint-id>.appsync-realtime-api.ca-west-1.amazonaws.com",
+            "HTTP": "<endpoint-id>.appsync-api.ca-west-1.amazonaws.com"
+        },
+        "apiArn": "arn:aws:appsync:us-east-1:000000000000:apis/<api-id>",
+        "created": "2025-07-14T11:38:32.594000-06:00",
+        "eventConfig": {...}
+    }
+}
+```
+
+#### 2. Create a `channelNamespace`
+
+You can create an `channelNamespace` using the [CreateChannelNamespace](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateChannelNamespace.html) API. At least one `channelNamespace` is required in order to subscribe and publish to it.
+
+```bash
+awslocal appsync create-channel-namespace \
+    --api-id <api-id> \
+    --name "default"
+```
+
+```bash title="Output"
+{
+    "channelNamespace": {
+        "apiId": "<api-id>",
+        "name": "default",
+        "tags": {},
+        "channelNamespaceArn": "arn:aws:appsync:us-east-1:000000000000:apis/<api-id>/channelNamespace/default",
+        "created": "2025-07-14T11:39:44.554000-06:00",
+        "lastModified": "2025-07-14T11:39:44.554000-06:00",
+        "handlerConfigs": {}
+    }
+}
+
+```
+
+#### 3. Create an API Key
+
+You can create an Api Key using the [CreateApiKey](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateApiKey.html) API. The Api Key is used to authenticate Websocket connections and authorize `publish` and `subscribe` events. Note you Api Key id as it will be referenced as `<api-key-id>` in this example.
+
+
+```bash
+awslocal appsync create-api-key --api-id <api-id>
+```
+
+```bash title="Output"
+{
+    "apiKey": {
+        "id": "<api-key-id>",
+        "expires": 1753117200,
+        "deletes": 1758301200
+    }
+}
+```
+
+#### 4. Connect via WebSocket
+
+This example will use `wscat` to create a WebSocket connection. From there, we will create a subscription and show an example of how to publish via WebSocket and HTTP. If you do not have it installed, it can be installed as a `npm` global package with the following command.
+
+```bash
+npm install -g wscat
+```
+
+Export to your shell all of the required configuration. Note that we are base64 encoding the headers in a url safe manner.
+
+```bash
+export HTTP_DOMAIN=<http-domain>
+export REALTIME_DOMAIN=<realtime-domain>
+export API_KEY=<api-key-id>
+export HEADER="{\"host\":\"$HTTP_DOMAIN\", \"x-api-key\":\"$API_KEY\"}"
+export HEADER=`echo "$HEADER" | base64 | tr '+/' '-_' | tr -d '\n='`
+```
+
+Using `wscat` you can now connect to your api. Note that we are sending the base64 encoded header map as subprotocol.
+
+```bash
+wscat \
+    -s "header-$HEADER" \
+    -s "aws-appsync-event-ws" \
+    -c "ws://$REALTIME_DOMAIN/event/realtime"
+```
+
+```bash title="Output"
+Connected (press CTRL+C to quit)
+> |
+```
+
+#### 5. Subscribe to a channel
+
+Once connected a `subscribe` event containing the following keys can be sent: `type`, `id`, `channel` and `authorization`.
+The connection `id` is later reused when receiving events from this subscription and when sending an `unsubscribe` event.
+
+```
+{"type": "subscribe", "channel": "/default/*", "id": "1234567890", "authorization": { "x-api-key": "<api-key-id>"}}
+```
+
+```bash title="Output"
+< {"id":"1234567890","type":"subscribe_success"}
+```
+
+#### 6. Publish via WebSocket
+
+Once subscribed, a `publish` event can be sent. Note that the subscription create to listen to every sub-channel of `default` via `/default/*` so publish event sent to `/default/race` or `/default/race/formulaOne` would be received by the subscriber, but events published to root `/default`, in this case would not be received.
+
+A `subscribe` event contains the following keys: `type`, `channel`, `events` and `authorization`. Note that `events` must be a list of JSON string.
+
+```
+{"type": "publish", "channel": "/default/race", "events": ["{\"team\": \"McLaren\"}"], "authorization": {"x-api-key": "<api-key-id>"}, "id": "000"}
+```
+
+The `publish_success` event is received first followed by the published event
+
+```bash title="Output"
+< {"id":"000","type":"publish_success","successful":[{"identifier":"7e77f331-bf1b-4e42-9c9e-6e7c34dcf7f2","index":0}],"failed":[]}
+< {"id":"1234567890","type":"data","event":"{\"team\": \"McLaren\"}"}
+```
+
+#### 7. Publish via HTTP
+
+Create a file named `publishEvent.json` with and paste within the following content.
+
+```json
+{
+    "channel": "default/channel",
+    "events": [
+        "{\"event_1\":\"data_1\"}",
+        "{\"event_2\":\"data_2\"}"
+    ]
+}
+```
+
+In a separate terminal from your WebSocket connection, make a `POST` request containing a `publish` event can be sent to the http endpoint.
 
-You can employ a pre-defined ID during the creation of GraphQL APIs by utilizing the special tag `_custom_id_`.
-For example, the following command will create a GraphQL API with the ID `faceb00c`:
+```bash
+curl -X POST "http://${HTTP_DOMAIN}/event" \
+    -d @publishEvent.json \
+    -H "x-api-key: ${API_KEY}" \
+    -H "content-type: application/json"
+```
+
+```bash title="Output"
+{
+    "failed": [],
+    "successful": [
+        {
+            "identifier": "1260cde1-a50c-410d-9eee-9932eb32511d",
+            "index": 0
+        },
+        {
+            "identifier": "5f4e1897-9295-4ac0-a6fd-185736e48744",
+            "index": 1
+        }
+    ]
+}
+```
+
+In your terminal with the WebSocket Connection, you can now see the 2 new events
+
+```bash title="Output"
+< {"id":"1234567890","type":"data","event":"{\"event_1\":\"data_1\"}"}
+< {"id":"1234567890","type":"data","event":"{\"event_2\":\"data_2\"}"}
+```
+
+## Shared configurations
+
+### Custom API IDs
+
+You can employ a pre-defined ID during the creation of AppSync APIs by utilizing the special tag `_custom_id_`.
+For example, the following command will create a GraphQL API with the ID `faceb00c`. `--tags` can also be passed when creating an Events API, and both the API id and the endpoint id will use the provided id.
 
 ```bash
 awslocal appsync create-graphql-api \
@@ -210,17 +417,18 @@ awslocal appsync create-graphql-api \
 }
 ```
 
-## GraphQL Data sources
+### Data sources
 
 LocalStack supports the following data source types types and services:
 
-| Resolver Type         | Description                                                            |
-| --------------------- | ---------------------------------------------------------------------- |
-| `AMAZON_DYNAMODB`     | Provides access to DynamoDB tables.                                    |
-| `RELATIONAL_DATABASE` | Provides access to RDS database tables.                                |
-| `AWS_LAMBDA`          | Allows retrieval of data from Lambda function invocations.             |
-| `HTTP`                | Enables calling HTTP endpoints to fetch data.                          |
-| `NONE`                | Used for pass-through resolver mapping templates returning input data. |
+| Resolver Type             | Description                                                            |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `AMAZON_DYNAMODB`         | Provides access to DynamoDB tables.                                    |
+| `RELATIONAL_DATABASE`     | Provides access to RDS database tables.                                |
+| `AWS_LAMBDA`              | Allows retrieval of data from Lambda function invocations.             |
+| `HTTP`                    | Enables calling HTTP endpoints to fetch data.                          |
+| `NONE` (GraphQL API Only) | Used for pass-through resolver mapping templates returning input data. |
+
 
 ## GraphQL resolvers
 
@@ -230,7 +438,8 @@ Unit resolvers consist of request and response mapping templates, facilitating t
 Pipeline resolvers, on the other hand, invoke AppSync functions that wraps the AppSync data sources.
 Unit resolvers are written in the Velocity templating language (VTL), while pipeline resolvers can be written in either VTL or JavaScript.
 
-## Configuring GraphQL Endpoints
+
+## Configuring GraphQL endpoints
 
 There are three configurable strategies that govern how GraphQL API endpoints are created.
 The strategy can be configured via the `GRAPHQL_ENDPOINT_STRATEGY` environment variable.
@@ -241,11 +450,26 @@ The strategy can be configured via the `GRAPHQL_ENDPOINT_STRATEGY` environment v
 | `path`   | `localhost:4566/appsync-api/<api-id>/graphql`         | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. |
 | `legacy` | `localhost:4566/graphql/<api-id>`                    | This strategy represents the old endpoint format, which is currently the default but will eventually be phased out. |
 
-## Resolver evaluation endpoints
 
-LocalStack supports the resolver evaluation endpoints: [`EvaluateCode`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_EvaluateCode.html) and [`EvaluateMappingTemplate`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_EvaluateMappingTemplate.html).
+## Event handlers
+
+LocalStack supports configuring [code handlers](https://docs.aws.amazon.com/appsync/latest/eventapi/runtime-reference-overview.html) for your channel namespace. Code handlers can be configured with or without [data sources](#data-sources).
-LocalStack supports configuring [code handlers](https://docs.aws.amazon.com/appsync/latest/eventapi/runtime-reference-overview.html) for your channel namespace. Code handlers can be configured with or without [data sources](#data-sources).
+LocalStack supports configuring [code handlers](https://docs.aws.amazon.com/appsync/latest/eventapi/runtime-reference-overview.html) for your [channel namespace](#2-create-a-channelnamespace). Code handlers can be configured with or without [data sources](#data-sources).
-LocalStack supports configuring [code handlers](https://docs.aws.amazon.com/appsync/latest/eventapi/runtime-reference-overview.html) for your channel namespace. Code handlers can be configured with or without [data sources](#data-sources).
+LocalStack supports configuring [code handlers](https://docs.aws.amazon.com/appsync/latest/eventapi/runtime-reference-overview.html) for your [channel namespace](#2-create-a-channelnamespace). Code handlers can be configured with or without [data sources](#data-sources).
 
-Resolver code can be either passed in as a string, or from a file with the `file://` prefix for the `--template/--code` arguments.
+## Configuring Event endpoints
+
+We are registering 2 type of endpoints that you can use to target you Events API. The examples represent the HTTP endpoint with `appsync-api` but the same is true for REALTIME endpoint with `appsync-realtime-api`. Note that unlike for GraphQL APIs, Events API endpoint is isn't the same as the API ID.
+
+| Value    | Format                                                 | Description                                                                                         |
+|----------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `domain` | `<endpoint-id>.appsync-api.localhost.localstack.cloud:4566` | This strategy, uses the `localhost.localstack.cloud` domain to route to your localhost. |
+| `path`   | `localhost:4566/_aws/appsync-api/<endpoint-id>`         | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. |
+
+
+## Evaluation endpoints
+
+LocalStack supports code evaluation endpoints: [`EvaluateCode`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_EvaluateCode.html) and [`EvaluateMappingTemplate`](https://docs.aws.amazon.com/appsync/latest/APIReference/API_EvaluateMappingTemplate.html).
+
+Code can be either passed in as a string, or from a file with the `file://` prefix for the `--template/--code` arguments.
 See the AWS documentation for [`evaluate-mapping-template`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/evaluate-mapping-template.html) and [`evaluate-code`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/evaluate-code.html) for more details.
 
 ### VTL resolver templates
-### VTL resolver templates
+### VTL template evaluation
-### VTL resolver templates
+### VTL template evaluation
@@ -263,13 +487,13 @@ awslocal appsync evaluate-mapping-template \
 }
 ```
 
-### JavaScript resolvers
+### JavaScript code evaluation
 
 ```bash
 awslocal appsync evaluate-code \
     --runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
     --function request \
-    --code 'export function request(ctx) { return ctx.result; }; export function response(ctx) {};' \
+    --code 'export function request(ctx) { return ctx.result; } export function response(ctx) {}' \
     --context '{"result": "ok"}'
 ```
 
@@ -282,6 +506,8 @@ awslocal appsync evaluate-code \
 
 ## Resource Browser
 
+### GraphQL API
+
 The LocalStack Web Application provides a Resource Browser for managing AppSync APIs, Data Sources, Schema, Query, Types, Resolvers, Functions and API keys.
 You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the **Resources** section, and then clicking on **AppSync** under the **App Integration** section.
 
@@ -308,6 +534,12 @@ The Resource Browser allows you to perform the following actions:
 - **Create Function**: Click on the GraphQL API name and click **Functions**.
   Click on **Create Function** to create a function, by providing a name for the function, data source name, and Function Version, Request Mapping Template, Response Mapping Template, among other parameters, before clicking **Submit**.
 
+### Events API
+
+:::note
+Resource Browser support for Events APIs is not available yet.
+:::
+
 ## Examples
 
 The following code snippets and sample applications provide practical examples of how to use AppSync in LocalStack for various use cases: