diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 7a69dbfe..2c50a10a 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -8,20 +8,35 @@ 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 +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 and Events API. + +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 + +Use schemas and resolvers to interact with data sources like DynamoDB. + +### Getting Started + +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 +64,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 +109,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 +152,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 +179,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 +195,277 @@ awslocal appsync create-resolver \ --response-mapping-template file://response-mapping-template.vtl ``` -## Custom GraphQL API IDs +### GraphQL resolvers + +LocalStack's AppSync offers support for both unit and pipeline resolvers, as detailed in the [AWS resolvers documentation](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html). +Unit resolvers consist of request and response mapping templates, facilitating the transformation of requests to and from data sources. + +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 + +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**. -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`: + +## Events API + +Enable sending real-time event data to subscribed clients. + +### Getting Started + +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 ``, `` and `` 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": "", + "name": "my-api", + "tags": {}, + "dns": { + "REALTIME": ".appsync-realtime-api.ca-west-1.amazonaws.com", + "HTTP": ".appsync-api.ca-west-1.amazonaws.com" + }, + "apiArn": "arn:aws:appsync:us-east-1:000000000000:apis/", + "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 \ + --name "default" +``` + +```bash title="Output" +{ + "channelNamespace": { + "apiId": "", + "name": "default", + "tags": {}, + "channelNamespaceArn": "arn:aws:appsync:us-east-1:000000000000:apis//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 `` in this example. + + +```bash +awslocal appsync create-api-key --api-id +``` + +```bash title="Output" +{ + "apiKey": { + "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= +export REALTIME_DOMAIN= +export API_KEY= +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": ""}} +``` + +```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": ""}, "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. + +```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\"}"} +``` + + +### Event code handlers + +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). + +### 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` | `.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/` | An alternative strategy that can be beneficial if you're unable to resolve LocalStack's `localhost` domain. | + + +### Events Resource Browser + +:::note +Resource Browser support for Events APIs is not available yet. +::: + + +## 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,45 +492,27 @@ 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 - -LocalStack's AppSync offers support for both unit and pipeline resolvers, as detailed in the [AWS resolvers documentation](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html). -Unit resolvers consist of request and response mapping templates, facilitating the transformation of requests to and from data sources. - -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 - -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. | -## Resolver evaluation endpoints +## 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). +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). -Resolver code can be either passed in as a string, or from a file with the `file://` prefix for the `--template/--code` arguments. +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 template evaluation ```bash awslocal appsync evaluate-mapping-template \ @@ -263,13 +527,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"}' ``` @@ -280,33 +544,6 @@ awslocal appsync evaluate-code \ } ``` -## 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**. ## Examples