From ffcaa3fe82aecf23875b46a345536655f898a0bd Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 22 Aug 2025 09:07:54 -0700 Subject: [PATCH 1/7] Document WebSocket subscriptions for AppSync Added documentation for WebSocket subscriptions in AWS AppSync using LocalStack, including setup instructions and message types. --- src/content/docs/aws/services/appsync.mdx | 154 ++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 2c50a10a..5f57359f 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -245,6 +245,160 @@ The Resource Browser allows you to perform the following actions: 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**. +## WebSocket Subscriptions + +LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. Clients can subscribe to mutation-triggered events and receive updates in real time via the AppSync WebSocket endpoint. LocalStack supports the GraphQL `@aws_subscribe` directive, core subscription message flow, and API Key-based authentication. + +Use this feature to power live updates in apps such as chat, dashboards, or collaborative editors. There's no need to poll for changes. + +### Getting Started + +Set up a GraphQL subscription in your schema, connect to the WebSocket endpoint, and receive live updates triggered by a mutation. + +#### 1. Extend Your GraphQL Schema + +First, ensure your schema includes a `subscription` type. Use the `@aws_subscribe` directive to link each subscription to a corresponding mutation. + +```graphql +type Message { + id: ID! + content: String! +} + +type Mutation { + postMessage(id: ID!, content: String!): Message! +} + +type Subscription { + onMessagePosted: Message + @aws_subscribe(mutations: ["postMessage"]) +} + +schema { + query: Query + mutation: Mutation + subscription: Subscription +} +``` + +#### 2. Connect to the WebSocket Endpoint + +LocalStack exposes a WebSocket endpoint for each GraphQL API: + +```json +"REALTIME": "ws://localhost:4510/graphql/" +``` + +Use a WebSocket client like `wscat` to connect: + +```bash +npm install -g wscat + +export API_ID= +export API_KEY= +export HEADER="{\"host\":\"localhost:4566\",\"x-api-key\":\"$API_KEY\"}" +export HEADER_ENCODED=$(echo -n $HEADER | base64 | tr '+/' '-_' | tr -d '=') + +wscat \ + -s "header-$HEADER_ENCODED" \ + -s "graphql-ws" \ + -c "ws://localhost:4510/graphql/$API_ID" +``` + +#### 3. Initialize the WebSocket Connection + +After connecting, send a `connection_init` message: + +```json +{ "type": "connection_init" } +``` + +You should receive a `connection_ack` in response. + +#### 4. Start a Subscription + +Use a `start` message to register your subscription: + +```json +{ + "id": "1", + "type": "start", + "payload": { + "data": "{\"query\":\"subscription { onMessagePosted { id content } }\"}" + } +} +``` + +#### 5. Trigger the Subscription + +Now, trigger the matching mutation: + +```bash +awslocal appsync graphql \ + --api-id $API_ID \ + --query 'mutation { postMessage(id: "1", content: "Hello world!") { id content } }' +``` + +You should see a live message from the WebSocket server like: + +```json title="Output" +{ + "type": "data", + "id": "1", + "payload": { + "data": { + "onMessagePosted": { + "id": "1", + "content": "Hello world!" + } + } + } +} +``` + +#### 6. Stop the Subscription + +To unregister, send a `stop` message: + +```json +{ "type": "stop", "id": "1" } +``` + +You'll receive a `complete` message when successful. + + +### Configuring WebSocket endpoints + +The WebSocket endpoint for GraphQL subscriptions is provided in the `uris` section of the `create-graphql-api` response. + +Example: + +```json +"uris": { + "GRAPHQL": "http://localhost:4566/graphql/", + "REALTIME": "ws://localhost:4510/graphql/" +} +``` + +To connect, encode your headers (such as `x-api-key` and `host`) as a base64 JSON string and provide it using the `Sec-WebSocket-Protocol` header prefixed with `header-`. Use `graphql-ws` as the subprotocol. + +Only `API_KEY` authentication is currently supported for WebSocket connections in LocalStack. Other methods like Cognito, IAM, and Lambda are not yet implemented. + +LocalStack supports the following WebSocket message types: + +| Type | Description | +| ----------------- | ----------------------------------------------- | +| `connection_init` | Client initiates connection | +| `connection_ack` | Server acknowledges the connection | +| `ka` | Keep-alive (heartbeat) message | +| `start` | Starts a subscription | +| `start_ack` | Acknowledges a successful subscription | +| `data` | Sends a message when a matching mutation occurs | +| `stop` | Client unsubscribes from a subscription | +| `complete` | Server confirms unsubscription | + + + ## Events API Enable sending real-time event data to subscribed clients. From 3a41d5d1775ccba7564898fbefb877a8feaf07c6 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Mon, 25 Aug 2025 08:30:50 -0700 Subject: [PATCH 2/7] Update src/content/docs/aws/services/appsync.mdx Co-authored-by: Mathieu Cloutier <79954947+cloutierMat@users.noreply.github.com> --- src/content/docs/aws/services/appsync.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 5f57359f..1b9d33a7 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -334,10 +334,10 @@ Use a `start` message to register your subscription: Now, trigger the matching mutation: ```bash -awslocal appsync graphql \ - --api-id $API_ID \ - --query 'mutation { postMessage(id: "1", content: "Hello world!") { id content } }' -``` +curl -X POST http://${API_ID}.appsync-api.localhost.localstack.cloud:4566/graphql \ + -H "content-type: application/json" \ + -H "x-api-key: ${API_KEY}" \ + -d '{"query": "mutation { postMessage(id: \"1\", content: \"Hello world!\") { id content } }" }' You should see a live message from the WebSocket server like: From 5efe6a7cfb02c248c96c3ad0a91bca2ebfc63b4d Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Mon, 25 Aug 2025 08:32:28 -0700 Subject: [PATCH 3/7] Apply suggestions from code review --- src/content/docs/aws/services/appsync.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 1b9d33a7..fc6d21d1 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -247,7 +247,7 @@ The Resource Browser allows you to perform the following actions: ## WebSocket Subscriptions -LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. Clients can subscribe to mutation-triggered events and receive updates in real time via the AppSync WebSocket endpoint. LocalStack supports the GraphQL `@aws_subscribe` directive, core subscription message flow, and API Key-based authentication. +LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. Clients can subscribe to mutation-triggered events and receive updates in real time via the AppSync WebSocket endpoint. LocalStack supports the GraphQL `@aws_subscribe` directive, and core subscription message flow. Use this feature to power live updates in apps such as chat, dashboards, or collaborative editors. There's no need to poll for changes. @@ -390,7 +390,6 @@ LocalStack supports the following WebSocket message types: | ----------------- | ----------------------------------------------- | | `connection_init` | Client initiates connection | | `connection_ack` | Server acknowledges the connection | -| `ka` | Keep-alive (heartbeat) message | | `start` | Starts a subscription | | `start_ack` | Acknowledges a successful subscription | | `data` | Sends a message when a matching mutation occurs | From 5015dcc1f75110d4891d63d386169a9e8bc36435 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Mon, 25 Aug 2025 10:26:19 -0700 Subject: [PATCH 4/7] remove incorrect authentication & optional content --- src/content/docs/aws/services/appsync.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index fc6d21d1..688c1af7 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -300,7 +300,6 @@ export HEADER="{\"host\":\"localhost:4566\",\"x-api-key\":\"$API_KEY\"}" export HEADER_ENCODED=$(echo -n $HEADER | base64 | tr '+/' '-_' | tr -d '=') wscat \ - -s "header-$HEADER_ENCODED" \ -s "graphql-ws" \ -c "ws://localhost:4510/graphql/$API_ID" ``` @@ -380,9 +379,6 @@ Example: } ``` -To connect, encode your headers (such as `x-api-key` and `host`) as a base64 JSON string and provide it using the `Sec-WebSocket-Protocol` header prefixed with `header-`. Use `graphql-ws` as the subprotocol. - -Only `API_KEY` authentication is currently supported for WebSocket connections in LocalStack. Other methods like Cognito, IAM, and Lambda are not yet implemented. LocalStack supports the following WebSocket message types: From 257b365c3d029c4664848b9060519d970294f1a5 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Mon, 25 Aug 2025 10:41:35 -0700 Subject: [PATCH 5/7] Draft 2 --- src/content/docs/aws/services/appsync.mdx | 109 +++++++++++----------- 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 688c1af7..efdfda62 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -204,58 +204,15 @@ Pipeline resolvers, on the other hand, invoke AppSync functions that wraps the A Unit resolvers are written in the Velocity templating language (VTL), while pipeline resolvers can be written in either VTL or JavaScript. -### 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. - -| Value | Format | Description | -|----------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------| -| `domain` | `.appsync-api.localhost.localstack.cloud:4566` | This strategy, slated to be the future default, uses the `localhost.localstack.cloud` domain to route to your localhost. | -| `path` | `localhost:4566/appsync-api//graphql` | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. | -| `legacy` | `localhost:4566/graphql/` | This strategy represents the old endpoint format, which is currently the default but will eventually be phased out. | - - -### GraphQL Resource Browser - -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. - -![AppSync Resource Browser](/images/aws/appsync-resource-browser.png) - -The Resource Browser allows you to perform the following actions: - -- **Create API**: Create a new GraphQL API by clicking **Create API** and providing a name for the API, Authentication Type, and optional tags among other parameters. -- **Edit API**: Click on the GraphQL API name and click **Edit API** to edit the GraphQL API, by updating the parameters before clicking **Submit**. -- **Create Data Source**: Click on the GraphQL API name and click **Data Source**. - Click on **Create Data Source** to create a new data source for the GraphQL API, by providing a name for the data source, data source type, and Service Role ARN before clicking **Submit**. -- **Edit Data Source**: Click on the GraphQL API name and click **Data Source**. - Click on the data source name and click **Edit Data Source** to edit the data source, by updating the parameters before clicking **Submit**. -- **Create Types**: Click on the GraphQL API name and click **Types**. - Click on **Create Type** to create a type definition, in GraphQL Schema Definition Language (SDL) format, before clicking **Submit**. -- **Create API Key**: Click on the GraphQL API name and click **API Keys**. - Click on **Create API Key** to create an API key for the GraphQL API, by providing a description for the API key and its expiration time before clicking **Submit**. -- **View and edit Schema**: Click on the GraphQL API name and click **Schema**. - You can view the GraphQL schema, and edit the GraphQL schema, in GraphQL Schema Definition Language (SDL) format, before clicking **Update**. -- **Query**: Click on the GraphQL API name and click **Query**. - You can query the GraphQL API by providing the GraphQL query and variables, including the operation and API key, before clicking **Execute**. -- **Attach Resolver**: Click on the GraphQL API name and click **Resolvers**. - Click on **Attach Resolver** to attach a resolver to a field, by providing the field name, data source name, Request Mapping Template, Response Mapping Template, among other parameters, before clicking **Submit**. -- **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**. - - ## WebSocket Subscriptions -LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. Clients can subscribe to mutation-triggered events and receive updates in real time via the AppSync WebSocket endpoint. LocalStack supports the GraphQL `@aws_subscribe` directive, and core subscription message flow. +LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. -Use this feature to power live updates in apps such as chat, dashboards, or collaborative editors. There's no need to poll for changes. +Clients can subscribe to mutation-triggered events and receive updates in real time via the AppSync WebSocket endpoint. LocalStack supports the GraphQL `@aws_subscribe` directive, and core subscription message flow. Use this feature to power live updates in apps such as chat, dashboards, or collaborative editors. There's no need to poll for changes. -### Getting Started +You can set up a GraphQL subscription in your schema, connect to the WebSocket endpoint, and receive live updates triggered by a mutation. -Set up a GraphQL subscription in your schema, connect to the WebSocket endpoint, and receive live updates triggered by a mutation. - -#### 1. Extend Your GraphQL Schema +### 1. Extend Your GraphQL Schema First, ensure your schema includes a `subscription` type. Use the `@aws_subscribe` directive to link each subscription to a corresponding mutation. @@ -281,7 +238,7 @@ schema { } ``` -#### 2. Connect to the WebSocket Endpoint +### 2. Connect to the WebSocket Endpoint LocalStack exposes a WebSocket endpoint for each GraphQL API: @@ -304,7 +261,7 @@ wscat \ -c "ws://localhost:4510/graphql/$API_ID" ``` -#### 3. Initialize the WebSocket Connection +### 3. Initialize the WebSocket Connection After connecting, send a `connection_init` message: @@ -314,7 +271,7 @@ After connecting, send a `connection_init` message: You should receive a `connection_ack` in response. -#### 4. Start a Subscription +### 4. Start a Subscription Use a `start` message to register your subscription: @@ -328,7 +285,7 @@ Use a `start` message to register your subscription: } ``` -#### 5. Trigger the Subscription +### 5. Trigger the Subscription Now, trigger the matching mutation: @@ -355,7 +312,7 @@ You should see a live message from the WebSocket server like: } ``` -#### 6. Stop the Subscription +### 6. Stop the Subscription To unregister, send a `stop` message: @@ -366,7 +323,7 @@ To unregister, send a `stop` message: You'll receive a `complete` message when successful. -### Configuring WebSocket endpoints +### Configuring WebSocket Subscription endpoints The WebSocket endpoint for GraphQL subscriptions is provided in the `uris` section of the `create-graphql-api` response. @@ -379,7 +336,6 @@ Example: } ``` - LocalStack supports the following WebSocket message types: | Type | Description | @@ -393,6 +349,51 @@ LocalStack supports the following WebSocket message types: | `complete` | Server confirms unsubscription | +### 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. + +| Value | Format | Description | +|----------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------| +| `domain` | `.appsync-api.localhost.localstack.cloud:4566` | This strategy, slated to be the future default, uses the `localhost.localstack.cloud` domain to route to your localhost. | +| `path` | `localhost:4566/appsync-api//graphql` | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. | +| `legacy` | `localhost:4566/graphql/` | This strategy represents the old endpoint format, which is currently the default but will eventually be phased out. | + +:::note +The `REALTIME` endpoint will ignore the `GRAPHQL_ENDPOINT_STRATEGY` and always use the `legacy` strategy. +::: + + +### GraphQL Resource Browser + +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. + +![AppSync Resource Browser](/images/aws/appsync-resource-browser.png) + +The Resource Browser allows you to perform the following actions: + +- **Create API**: Create a new GraphQL API by clicking **Create API** and providing a name for the API, Authentication Type, and optional tags among other parameters. +- **Edit API**: Click on the GraphQL API name and click **Edit API** to edit the GraphQL API, by updating the parameters before clicking **Submit**. +- **Create Data Source**: Click on the GraphQL API name and click **Data Source**. + Click on **Create Data Source** to create a new data source for the GraphQL API, by providing a name for the data source, data source type, and Service Role ARN before clicking **Submit**. +- **Edit Data Source**: Click on the GraphQL API name and click **Data Source**. + Click on the data source name and click **Edit Data Source** to edit the data source, by updating the parameters before clicking **Submit**. +- **Create Types**: Click on the GraphQL API name and click **Types**. + Click on **Create Type** to create a type definition, in GraphQL Schema Definition Language (SDL) format, before clicking **Submit**. +- **Create API Key**: Click on the GraphQL API name and click **API Keys**. + Click on **Create API Key** to create an API key for the GraphQL API, by providing a description for the API key and its expiration time before clicking **Submit**. +- **View and edit Schema**: Click on the GraphQL API name and click **Schema**. + You can view the GraphQL schema, and edit the GraphQL schema, in GraphQL Schema Definition Language (SDL) format, before clicking **Update**. +- **Query**: Click on the GraphQL API name and click **Query**. + You can query the GraphQL API by providing the GraphQL query and variables, including the operation and API key, before clicking **Execute**. +- **Attach Resolver**: Click on the GraphQL API name and click **Resolvers**. + Click on **Attach Resolver** to attach a resolver to a field, by providing the field name, data source name, Request Mapping Template, Response Mapping Template, among other parameters, before clicking **Submit**. +- **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 From 047729ac1f6af1701c5370f80bb5188aa462d227 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 26 Aug 2025 13:10:30 -0700 Subject: [PATCH 6/7] improve WebSocket client like `wscat` code snippet Co-authored-by: Mathieu Cloutier <79954947+cloutierMat@users.noreply.github.com> --- src/content/docs/aws/services/appsync.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index efdfda62..9e3f0d28 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -252,14 +252,10 @@ Use a WebSocket client like `wscat` to connect: npm install -g wscat export API_ID= -export API_KEY= -export HEADER="{\"host\":\"localhost:4566\",\"x-api-key\":\"$API_KEY\"}" -export HEADER_ENCODED=$(echo -n $HEADER | base64 | tr '+/' '-_' | tr -d '=') wscat \ -s "graphql-ws" \ -c "ws://localhost:4510/graphql/$API_ID" -``` ### 3. Initialize the WebSocket Connection From 3dcbddb0404f5c2aa49597fed0d7b294ea604a32 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 26 Aug 2025 13:12:17 -0700 Subject: [PATCH 7/7] round 3 --- src/content/docs/aws/services/appsync.mdx | 44 ++++++++++++----------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 9e3f0d28..71009212 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -204,7 +204,7 @@ Pipeline resolvers, on the other hand, invoke AppSync functions that wraps the A Unit resolvers are written in the Velocity templating language (VTL), while pipeline resolvers can be written in either VTL or JavaScript. -## WebSocket Subscriptions +### WebSocket Subscriptions LocalStack supports real-time GraphQL subscriptions over WebSocket for AWS AppSync APIs. @@ -212,7 +212,7 @@ Clients can subscribe to mutation-triggered events and receive updates in real t You can set up a GraphQL subscription in your schema, connect to the WebSocket endpoint, and receive live updates triggered by a mutation. -### 1. Extend Your GraphQL Schema +#### 1. Extend Your GraphQL Schema First, ensure your schema includes a `subscription` type. Use the `@aws_subscribe` directive to link each subscription to a corresponding mutation. @@ -238,7 +238,7 @@ schema { } ``` -### 2. Connect to the WebSocket Endpoint +#### 2. Connect to the WebSocket Endpoint LocalStack exposes a WebSocket endpoint for each GraphQL API: @@ -256,8 +256,9 @@ export API_ID= wscat \ -s "graphql-ws" \ -c "ws://localhost:4510/graphql/$API_ID" +``` -### 3. Initialize the WebSocket Connection +#### 3. Initialize the WebSocket Connection After connecting, send a `connection_init` message: @@ -267,7 +268,7 @@ After connecting, send a `connection_init` message: You should receive a `connection_ack` in response. -### 4. Start a Subscription +#### 4. Start a Subscription Use a `start` message to register your subscription: @@ -281,7 +282,7 @@ Use a `start` message to register your subscription: } ``` -### 5. Trigger the Subscription +#### 5. Trigger the Subscription Now, trigger the matching mutation: @@ -290,6 +291,7 @@ curl -X POST http://${API_ID}.appsync-api.localhost.localstack.cloud:4566/graphq -H "content-type: application/json" \ -H "x-api-key: ${API_KEY}" \ -d '{"query": "mutation { postMessage(id: \"1\", content: \"Hello world!\") { id content } }" }' +``` You should see a live message from the WebSocket server like: @@ -308,7 +310,7 @@ You should see a live message from the WebSocket server like: } ``` -### 6. Stop the Subscription +#### 6. Stop the Subscription To unregister, send a `stop` message: @@ -318,19 +320,7 @@ To unregister, send a `stop` message: You'll receive a `complete` message when successful. - -### Configuring WebSocket Subscription endpoints - -The WebSocket endpoint for GraphQL subscriptions is provided in the `uris` section of the `create-graphql-api` response. - -Example: - -```json -"uris": { - "GRAPHQL": "http://localhost:4566/graphql/", - "REALTIME": "ws://localhost:4510/graphql/" -} -``` +### Supported WebSocket Message Types LocalStack supports the following WebSocket message types: @@ -357,6 +347,20 @@ The strategy can be configured via the `GRAPHQL_ENDPOINT_STRATEGY` environment v | `path` | `localhost:4566/appsync-api//graphql` | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. | | `legacy` | `localhost:4566/graphql/` | This strategy represents the old endpoint format, which is currently the default but will eventually be phased out. | + +In addition to the GraphQL HTTP endpoint, each AppSync API also provides a WebSocket endpoint for GraphQL subscriptions. + +The WebSocket server runs on a separate port that may change between deployments. To ensure correct connectivity, always use the `REALTIME` URL returned in the `uris` field of the `create-graphql-api` or `get-graphql-api` responses. + +Example: + +```json +"uris": { + "GRAPHQL": "http://localhost:4566/graphql/", + "REALTIME": "ws://localhost:4510/graphql/" +} +``` + :::note The `REALTIME` endpoint will ignore the `GRAPHQL_ENDPOINT_STRATEGY` and always use the `legacy` strategy. :::