Amplify Graphql API Construct

This package vends an L3 CDK Construct wrapping the behavior of the Amplify GraphQL Transformer. This enables quick development and interation of AppSync APIs which support the Amplify GraphQL Directives. For more information on schema modeling in GraphQL, please refer to the amplify developer docs.

The primary way to use this construct is to invoke it with a provided schema (either as an inline graphql string, or as one or more appsync.SchemaFile) objects, and with authorization config provided. There are 5 supported methods for authorization of an AppSync API, all of which are supported by this construct. For more information on authorization rule definitions in Amplify, refer to the authorization docs. Note: currently at least one authorization rule is required, and if multiple are specified, a defaultAuthorizationMode must be specified on the api as well. Specified authorization modes must be a superset of those configured in the graphql schema.

Examples

Simple Todo List With Cognito Userpool-based Owner Authorization

In this example, we create a single model, which will use user pool auth in order to allow logged in users to create and manage their own todos privately.

We create a cdk App and Stack, though you may be deploying this to a custom stack, this is purely illustrative for a concise demo.

We then wire this through to import a user pool which was already deployed (creating and deploying is out of scope for this example).

import { App, Stack } from 'aws-cdk-lib';
import { UserPool } from 'aws-cdk-lib/aws-cognito';
import { AmplifyGraphqlApi, AmplifyGraphqlDefinition } from '@aws-amplify/graphql-api-construct';

const app = new App();
const stack = new Stack(app, 'TodoStack');

new AmplifyGraphqlApi(stack, 'TodoApp', {
  definition: AmplifyGraphqlDefinition.fromString(/* GraphQL */ `
    type Todo @model @auth(rules: [{ allow: owner }]) {
      description: String!
      completed: Boolean
    }
  `),
  authorizationModes: {
    userPoolConfig: {
      userPool: UserPool.fromUserPoolId(stack, 'ImportedUserPool', '<YOUR_USER_POOL_ID>'),
    },
  },
});

Multiple related models, with public read access, and admin read/write access

In this example, we create a two related models, which will use which logged in users in the 'Author' and 'Admin' user groups will have full access to, and customers requesting with api key will only have read permissions on.

import { App, Stack } from 'aws-cdk-lib';
import { UserPool } from 'aws-cdk-lib/aws-cognito';
import { AmplifyGraphqlApi, AmplifyGraphqlDefinition } from '@aws-amplify/graphql-api-construct';

const app = new App();
const stack = new Stack(app, 'BlogStack');

new AmplifyGraphqlApi(stack, 'BlogApp', {
  definition: AmplifyGraphqlDefinition.fromString(/* GraphQL */ `
    type Blog @model @auth(rules: [{ allow: public, operations: [read] }, { allow: groups, groups: ["Author", "Admin"] }]) {
      title: String!
      description: String
      posts: [Post] @hasMany
    }

    type Post @model @auth(rules: [{ allow: public, operations: [read] }, { allow: groups, groups: ["Author", "Admin"] }]) {
      title: String!
      content: [String]
      blog: Blog @belongsTo
    }
  `),
  authorizationModes: {
    defaultAuthorizationMode: 'API_KEY',
    apiKeyConfig: {
      description: 'Api Key for public access',
      expires: cdk.Duration.days(7),
    },
    userPoolConfig: {
      userPool: UserPool.fromUserPoolId(stack, 'ImportedUserPool', '<YOUR_USER_POOL_ID>'),
    },
  },
});

Import GraphQL Schema from files, instead of inline

In this example, we import the schema definition itself from one or more local files, rather than an inline graphql string.

# todo.graphql
type Todo @model @auth(rules: [{ allow: owner }]) {
  content: String!
  done: Boolean
}

# blog.graphql
type Blog @model @auth(rules: [{ allow: owner }, { allow: public, operations: [read] }]) {
  title: String!
  description: String
  posts: [Post] @hasMany
}

type Post @model @auth(rules: [{ allow: owner }, { allow: public, operations: [read] }]) {
  title: String!
  content: [String]
  blog: Blog @belongsTo
}

// app.ts
import { App, Stack } from 'aws-cdk-lib';
import { UserPool } from 'aws-cdk-lib/aws-cognito';
import { AmplifyGraphqlApi, AmplifyGraphqlDefinition } from '@aws-amplify/graphql-api-construct';

const app = new App();
const stack = new Stack(app, 'MultiFileStack');

new AmplifyGraphqlApi(stack, 'MultiFileDefinition', {
  definition: AmplifyGraphqlDefinition.fromFiles(path.join(__dirname, 'todo.graphql'), path.join(__dirname, 'blog.graphql')),
  authorizationModes: {
    defaultAuthorizationMode: 'API_KEY',
    apiKeyConfig: {
      description: 'Api Key for public access',
      expires: cdk.Duration.days(7),
    },
    userPoolConfig: {
      userPool: UserPool.fromUserPoolId(stack, 'ImportedUserPool', '<YOUR_USER_POOL_ID>'),
    },
  },
});

API Reference

Constructs

AmplifyGraphqlApi

L3 Construct which invokes the Amplify Transformer Pattern over an input Graphql Schema.

This can be used to quickly define appsync apis which support full CRUD+List and Subscriptions, relationships, auth, search over data, the ability to inject custom business logic and query/mutation operations, and connect to ML services.

For more information, refer to the docs links below: Data Modeling - https://docs.amplify.aws/cli/graphql/data-modeling/ Authorization - https://docs.amplify.aws/cli/graphql/authorization-rules/ Custom Business Logic - https://docs.amplify.aws/cli/graphql/custom-business-logic/ Search - https://docs.amplify.aws/cli/graphql/search-and-result-aggregations/ ML Services - https://docs.amplify.aws/cli/graphql/connect-to-machine-learning-services/

For a full reference of the supported custom graphql directives - https://docs.amplify.aws/cli/graphql/directives-reference/

The output of this construct is a mapping of L2 or L1 resources generated by the transformer, which generally follow the access pattern

  const api = new AmplifyGraphQlApi(this, 'api', { <params> });
  // Access L2 resources under `.resources`
  api.resources.tables["Todo"].tableArn;

  // Access L1 resources under `.resources.cfnResources`
  api.resources.cfnResources.cfnGraphqlApi.xrayEnabled = true;
  Object.values(api.resources.cfnResources.cfnTables).forEach(table => {
    table.pointInTimeRecoverySpecification = { pointInTimeRecoveryEnabled: false };
  });

resources.<ResourceType>.<ResourceName> - you can then perform any CDK action on these resulting resoureces.

Initializers

import { AmplifyGraphqlApi } from '@aws-amplify/graphql-api-construct'

new AmplifyGraphqlApi(scope: Construct, id: string, props: AmplifyGraphqlApiProps)

scope^Required

• Type: constructs.Construct

the scope to create this construct within.

id^Required

• Type: string

the id to use for this api.

props^Required

• Type: AmplifyGraphqlApiProps

the properties used to configure the generated api.

Methods

toString

public toString(): string

Returns a string representation of this construct.

addDynamoDbDataSource

public addDynamoDbDataSource(id: string, table: ITable, options?: DataSourceOptions): DynamoDbDataSource

Add a new DynamoDB data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

table^Required

• Type: aws-cdk-lib.aws_dynamodb.ITable

The DynamoDB table backing this data source.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addElasticsearchDataSource

public addElasticsearchDataSource(id: string, domain: IDomain, options?: DataSourceOptions): ElasticsearchDataSource

Add a new elasticsearch data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

domain^Required

• Type: aws-cdk-lib.aws_elasticsearch.IDomain

The elasticsearch domain for this data source.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addEventBridgeDataSource

public addEventBridgeDataSource(id: string, eventBus: IEventBus, options?: DataSourceOptions): EventBridgeDataSource

Add an EventBridge data source to this api.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

eventBus^Required

• Type: aws-cdk-lib.aws_events.IEventBus

The EventBridge EventBus on which to put events.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addFunction

public addFunction(id: string, props: AddFunctionProps): AppsyncFunction

Add an appsync function to the api.

id^Required

• Type: string

the function's id.

props^Required

• Type: AddFunctionProps

addHttpDataSource

public addHttpDataSource(id: string, endpoint: string, options?: HttpDataSourceOptions): HttpDataSource

Add a new http data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

endpoint^Required

• Type: string

The http endpoint.

options^Optional

• Type: aws-cdk-lib.aws_appsync.HttpDataSourceOptions

The optional configuration for this data source.

addLambdaDataSource

public addLambdaDataSource(id: string, lambdaFunction: IFunction, options?: DataSourceOptions): LambdaDataSource

Add a new Lambda data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

lambdaFunction^Required

• Type: aws-cdk-lib.aws_lambda.IFunction

The Lambda function to call to interact with this data source.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addNoneDataSource

public addNoneDataSource(id: string, options?: DataSourceOptions): NoneDataSource

Add a new dummy data source to this API.

This is a proxy method to the L2 GraphqlApi Construct. Useful for pipeline resolvers and for backend changes that don't require a data source.

id^Required

• Type: string

The data source's id.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addOpenSearchDataSource

public addOpenSearchDataSource(id: string, domain: IDomain, options?: DataSourceOptions): OpenSearchDataSource

dd a new OpenSearch data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

domain^Required

• Type: aws-cdk-lib.aws_opensearchservice.IDomain

The OpenSearch domain for this data source.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addRdsDataSource

public addRdsDataSource(id: string, serverlessCluster: IServerlessCluster, secretStore: ISecret, databaseName?: string, options?: DataSourceOptions): RdsDataSource

Add a new Rds data source to this API.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The data source's id.

serverlessCluster^Required

• Type: aws-cdk-lib.aws_rds.IServerlessCluster

The serverless cluster to interact with this data source.

secretStore^Required

• Type: aws-cdk-lib.aws_secretsmanager.ISecret

The secret store that contains the username and password for the serverless cluster.

databaseName^Optional

• Type: string

The optional name of the database to use within the cluster.

options^Optional

• Type: aws-cdk-lib.aws_appsync.DataSourceOptions

The optional configuration for this data source.

addResolver

public addResolver(id: string, props: ExtendedResolverProps): Resolver

Add a resolver to the api.

This is a proxy method to the L2 GraphqlApi Construct.

id^Required

• Type: string

The resolver's id.

props^Required

• Type: aws-cdk-lib.aws_appsync.ExtendedResolverProps

the resolver properties.

Static Functions

isConstruct

import { AmplifyGraphqlApi } from '@aws-amplify/graphql-api-construct'

AmplifyGraphqlApi.isConstruct(x: any)

Checks if x is a construct.

x^Required

• Type: any

Any object.

Properties

node^Required

public readonly node: Node;

• Type: constructs.Node

The tree node.

apiId^Required

public readonly apiId: string;

• Type: string

Generated Api Id.

May be a CDK Token.

generatedFunctionSlots^Required

public readonly generatedFunctionSlots: MutationFunctionSlot | QueryFunctionSlot | SubscriptionFunctionSlot[];

• Type: MutationFunctionSlot | QueryFunctionSlot | SubscriptionFunctionSlot[]

Resolvers generated by the transform process, persisted on the side in order to facilitate pulling a manifest for the purposes of inspecting and producing overrides.

graphqlUrl^Required

public readonly graphqlUrl: string;

• Type: string

Graphql URL For the generated API.

May be a CDK Token.

realtimeUrl^Required

public readonly realtimeUrl: string;

• Type: string

Realtime URL For the generated API.

May be a CDK Token.

resources^Required

public readonly resources: AmplifyGraphqlApiResources;

• Type: AmplifyGraphqlApiResources

Generated L1 and L2 CDK resources.

apiKey^Optional

public readonly apiKey: string;

• Type: string

Generated Api Key if generated.

May be a CDK Token.

Structs

AddFunctionProps

Input type properties when adding a new appsync.AppsyncFunction to the generated API. This is equivalent to the Omit<appsync.AppsyncFunctionProps, 'api'>.

Initializer

import { AddFunctionProps } from '@aws-amplify/graphql-api-construct'

const addFunctionProps: AddFunctionProps = { ... }

Properties

dataSource^Required

public readonly dataSource: BaseDataSource;

• Type: aws-cdk-lib.aws_appsync.BaseDataSource

the data source linked to this AppSync Function.

name^Required

public readonly name: string;

• Type: string

the name of the AppSync Function.

code^Optional

public readonly code: Code;

• Type: aws-cdk-lib.aws_appsync.Code
• Default: no code is used

The function code.

description^Optional

public readonly description: string;

• Type: string
• Default: no description

the description for this AppSync Function.

requestMappingTemplate^Optional

public readonly requestMappingTemplate: MappingTemplate;

• Type: aws-cdk-lib.aws_appsync.MappingTemplate
• Default: no request mapping template

the request mapping template for the AppSync Function.

responseMappingTemplate^Optional

public readonly responseMappingTemplate: MappingTemplate;

• Type: aws-cdk-lib.aws_appsync.MappingTemplate
• Default: no response mapping template

the response mapping template for the AppSync Function.

runtime^Optional

public readonly runtime: FunctionRuntime;

• Type: aws-cdk-lib.aws_appsync.FunctionRuntime
• Default: no function runtime, VTL mapping templates used

The functions runtime.

AmplifyDynamoDbModelDataSourceStrategy

Use custom resource type 'Custom::AmplifyDynamoDBTable' to provision table.

Initializer

import { AmplifyDynamoDbModelDataSourceStrategy } from '@aws-amplify/graphql-api-construct'

const amplifyDynamoDbModelDataSourceStrategy: AmplifyDynamoDbModelDataSourceStrategy = { ... }

Properties

dbType^Required

public readonly dbType: string;

• Type: string

provisionStrategy^Required

public readonly provisionStrategy: string;

• Type: string

AmplifyGraphqlApiCfnResources

L1 CDK resources from the Api which were generated as part of the transform.

These are potentially stored under nested stacks, but presented organized by type instead.

Initializer

import { AmplifyGraphqlApiCfnResources } from '@aws-amplify/graphql-api-construct'

const amplifyGraphqlApiCfnResources: AmplifyGraphqlApiCfnResources = { ... }

Properties

additionalCfnResources^Required

public readonly additionalCfnResources: {[ key: string ]: CfnResource};

• Type: {[ key: string ]: aws-cdk-lib.CfnResource}

Remaining L1 resources generated, keyed by logicalId.

amplifyDynamoDbTables^Required

public readonly amplifyDynamoDbTables: {[ key: string ]: AmplifyDynamoDbTableWrapper};

• Type: {[ key: string ]: AmplifyDynamoDbTableWrapper}

The Generated Amplify DynamoDb Table L1 resource wrapper, keyed by model type name.

cfnDataSources^Required

public readonly cfnDataSources: {[ key: string ]: CfnDataSource};

• Type: {[ key: string ]: aws-cdk-lib.aws_appsync.CfnDataSource}

The Generated AppSync DataSource L1 Resources, keyed by logicalId.

cfnFunctionConfigurations^Required

public readonly cfnFunctionConfigurations: {[ key: string ]: CfnFunctionConfiguration};

• Type: {[ key: string ]: aws-cdk-lib.aws_appsync.CfnFunctionConfiguration}

The Generated AppSync Function L1 Resources, keyed by logicalId.

cfnFunctions^Required

public readonly cfnFunctions: {[ key: string ]: CfnFunction};

• Type: {[ key: string ]: aws-cdk-lib.aws_lambda.CfnFunction}

The Generated Lambda Function L1 Resources, keyed by function name.

cfnGraphqlApi^Required

public readonly cfnGraphqlApi: CfnGraphQLApi;

• Type: aws-cdk-lib.aws_appsync.CfnGraphQLApi

The Generated AppSync Api L1 Resource.

cfnGraphqlSchema^Required

public readonly cfnGraphqlSchema: CfnGraphQLSchema;

• Type: aws-cdk-lib.aws_appsync.CfnGraphQLSchema

The Generated AppSync Schema L1 Resource.

cfnResolvers^Required

public readonly cfnResolvers: {[ key: string ]: CfnResolver};

• Type: {[ key: string ]: aws-cdk-lib.aws_appsync.CfnResolver}

The Generated AppSync Resolver L1 Resources, keyed by logicalId.

cfnRoles^Required

public readonly cfnRoles: {[ key: string ]: CfnRole};

• Type: {[ key: string ]: aws-cdk-lib.aws_iam.CfnRole}

The Generated IAM Role L1 Resources, keyed by logicalId.

cfnTables^Required

public readonly cfnTables: {[ key: string ]: CfnTable};

• Type: {[ key: string ]: aws-cdk-lib.aws_dynamodb.CfnTable}

The Generated DynamoDB Table L1 Resources, keyed by logicalId.

cfnApiKey^Optional

public readonly cfnApiKey: CfnApiKey;

• Type: aws-cdk-lib.aws_appsync.CfnApiKey

The Generated AppSync Api Key L1 Resource.

AmplifyGraphqlApiProps

Input props for the AmplifyGraphqlApi construct.

Specifies what the input to transform into an Api, and configurations for the transformation process.

Initializer

import { AmplifyGraphqlApiProps } from '@aws-amplify/graphql-api-construct'

const amplifyGraphqlApiProps: AmplifyGraphqlApiProps = { ... }

Properties

authorizationModes^Required

public readonly authorizationModes: AuthorizationModes;

• Type: AuthorizationModes

Required auth modes for the Api.

This object must be a superset of the configured auth providers in the Api definition. For more information, refer to https://docs.amplify.aws/cli/graphql/authorization-rules/

definition^Required

public readonly definition: IAmplifyGraphqlDefinition;

• Type: IAmplifyGraphqlDefinition

The definition to transform in a full Api.

Can be constructed via the AmplifyGraphqlDefinition class.

apiName^Optional

public readonly apiName: string;

• Type: string

Name to be used for the AppSync Api.

Default: construct id.

conflictResolution^Optional

• Deprecated: use dataStoreConfiguration instead.

public readonly conflictResolution: ConflictResolution;

• Type: ConflictResolution

Configure conflict resolution on the Api, which is required to enable DataStore Api functionality.

For more information, refer to https://docs.amplify.aws/lib/datastore/getting-started/q/platform/js/

dataStoreConfiguration^Optional

public readonly dataStoreConfiguration: DataStoreConfiguration;

• Type: DataStoreConfiguration

Configure DataStore conflict resolution on the Api.

Conflict resolution is required to enable DataStore Api functionality. For more information, refer to https://docs.amplify.aws/lib/datastore/getting-started/q/platform/js/

disableOutputStorage^Optional

public readonly disableOutputStorage: boolean;

• Type: boolean

Disables storing construct output.

Output storage should be disabled when creating multiple GraphQL APIs in a single CDK synthesis. outputStorageStrategy will be ignored if this is set to true.

functionNameMap^Optional

public readonly functionNameMap: {[ key: string ]: IFunction};

• Type: {[ key: string ]: aws-cdk-lib.aws_lambda.IFunction}

Lambda functions referenced in the definitions's.

functionSlots^Optional

public readonly functionSlots: MutationFunctionSlot | QueryFunctionSlot | SubscriptionFunctionSlot[];

• Type: MutationFunctionSlot | QueryFunctionSlot | SubscriptionFunctionSlot[]

Overrides for a given slot in the generated resolver pipelines.

For more information about what slots are available, refer to https://docs.amplify.aws/cli/graphql/custom-business-logic/#override-amplify-generated-resolvers.

outputStorageStrategy^Optional

public readonly outputStorageStrategy: IBackendOutputStorageStrategy;

• Type: IBackendOutputStorageStrategy

Strategy to store construct outputs.

If no outputStorageStrategey is provided a default strategy will be used.

predictionsBucket^Optional

public readonly predictionsBucket: IBucket;

• Type: aws-cdk-lib.aws_s3.IBucket

If using predictions, a bucket must be provided which will be used to search for assets.

stackMappings^Optional

public readonly stackMappings: {[ key: string ]: string};

• Type: {[ key: string ]: string}

StackMappings override the assigned nested stack on a per-resource basis.

Only applies to resolvers, and takes the form { <logicalId>: <stackName> } It is not recommended to use this parameter unless you are encountering stack resource count limits, and worth noting that after initial deployment AppSync resolvers cannot be moved between nested stacks, they will need to be removed from the app, then re-added from a new stack.

transformerPlugins^Optional

public readonly transformerPlugins: any[];

• Type: any[]

Provide a list of additional custom transformers which are injected into the transform process.

These custom transformers must be implemented with aws-cdk-lib >=2.80.0, and

translationBehavior^Optional

public readonly translationBehavior: PartialTranslationBehavior;

• Type: PartialTranslationBehavior

This replaces feature flags from the Api construct, for general information on what these parameters do, refer to https://docs.amplify.aws/cli/reference/feature-flags/#graphQLTransformer.

AmplifyGraphqlApiResources

Accessible resources from the Api which were generated as part of the transform.

These are potentially stored under nested stacks, but presented organized by type instead.

Initializer

import { AmplifyGraphqlApiResources } from '@aws-amplify/graphql-api-construct'

const amplifyGraphqlApiResources: AmplifyGraphqlApiResources = { ... }

Properties

cfnResources^Required

public readonly cfnResources: AmplifyGraphqlApiCfnResources;

• Type: AmplifyGraphqlApiCfnResources

L1 Cfn Resources, for when dipping down a level of abstraction is desirable.

functions^Required

public readonly functions: {[ key: string ]: IFunction};

• Type: {[ key: string ]: aws-cdk-lib.aws_lambda.IFunction}

The Generated Lambda Function L1 Resources, keyed by function name.

graphqlApi^Required

public readonly graphqlApi: IGraphqlApi;

• Type: aws-cdk-lib.aws_appsync.IGraphqlApi

The Generated AppSync Api L2 Resource, includes the Schema.

nestedStacks^Required

public readonly nestedStacks: {[ key: string ]: NestedStack};

• Type: {[ key: string ]: aws-cdk-lib.NestedStack}

Nested Stacks generated by the Api Construct.

roles^Required

public readonly roles: {[ key: string ]: IRole};

• Type: {[ key: string ]: aws-cdk-lib.aws_iam.IRole}

The Generated IAM Role L2 Resources, keyed by logicalId.

tables^Required

public readonly tables: {[ key: string ]: ITable};

• Type: {[ key: string ]: aws-cdk-lib.aws_dynamodb.ITable}

The Generated DynamoDB Table L2 Resources, keyed by logicalId.

ApiKeyAuthorizationConfig

Configuration for Api Keys on the Graphql Api.

Initializer

import { ApiKeyAuthorizationConfig } from '@aws-amplify/graphql-api-construct'

const apiKeyAuthorizationConfig: ApiKeyAuthorizationConfig = { ... }

Properties

expires^Required

public readonly expires: Duration;

• Type: aws-cdk-lib.Duration

A duration representing the time from Cloudformation deploy until expiry.

description^Optional

public readonly description: string;

• Type: string

Optional description for the Api Key to attach to the Api.

AuthorizationModes

Authorization Modes to apply to the Api.

At least one modes must be provided, and if more than one are provided a defaultAuthorizationMode must be specified. For more information on Amplify Api auth, refer to https://docs.amplify.aws/cli/graphql/authorization-rules/#authorization-strategies

Initializer

import { AuthorizationModes } from '@aws-amplify/graphql-api-construct'

const authorizationModes: AuthorizationModes = { ... }

Properties

adminRoles^Optional

• Deprecated: , use iamConfig.allowListedRoles instead.

public readonly adminRoles: IRole[];

• Type: aws-cdk-lib.aws_iam.IRole[]

A list of roles granted full R/W access to the Api.

apiKeyConfig^Optional

public readonly apiKeyConfig: ApiKeyAuthorizationConfig;

• Type: ApiKeyAuthorizationConfig

AppSync Api Key config, required if a 'apiKey' auth provider is specified in the Api.

Applies to 'public' auth strategy.

defaultAuthorizationMode^Optional

public readonly defaultAuthorizationMode: string;

• Type: string

Default auth mode to provide to the Api, required if more than one config type is specified.

iamConfig^Optional

public readonly iamConfig: IAMAuthorizationConfig;

• Type: IAMAuthorizationConfig

IAM Auth config, required if an 'iam' auth provider is specified in the Api.

Applies to 'public' and 'private' auth strategies.

lambdaConfig^Optional

public readonly lambdaConfig: LambdaAuthorizationConfig;

• Type: LambdaAuthorizationConfig

Lambda config, required if a 'function' auth provider is specified in the Api.

Applies to 'custom' auth strategy.

oidcConfig^Optional

public readonly oidcConfig: OIDCAuthorizationConfig;

• Type: OIDCAuthorizationConfig

Cognito OIDC config, required if a 'oidc' auth provider is specified in the Api.

Applies to 'owner', 'private', and 'group' auth strategies.

userPoolConfig^Optional

public readonly userPoolConfig: UserPoolAuthorizationConfig;

• Type: UserPoolAuthorizationConfig

Cognito UserPool config, required if a 'userPools' auth provider is specified in the Api.

Applies to 'owner', 'private', and 'group' auth strategies.

AutomergeConflictResolutionStrategy

Enable optimistic concurrency on the project.

Initializer

import { AutomergeConflictResolutionStrategy } from '@aws-amplify/graphql-api-construct'

const automergeConflictResolutionStrategy: AutomergeConflictResolutionStrategy = { ... }

Properties

detectionType^Required

public readonly detectionType: string;

• Type: string

The conflict detection type used for resolution.

handlerType^Required

public readonly handlerType: string;

• Type: string

This conflict resolution strategy executes an auto-merge.

For more information, refer to https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html#conflict-detection-and-resolution

ConflictResolution <a name="ConflictResolution" id="@aws-amplify/graphql-a

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.20.1 (2025-04-17)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.20.0 (2025-04-09)

Features

• graphql-api-construct: add PointInTimeRecoverySpecification setter (#3206) (55c7bda)

Reverts

• Revert "chore: upgrade to node 20 (#3250)" (#3255) (a2815c7), closes #3250 #3255

1.19.1 (2025-03-06)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.19.0 (2025-02-26)

Features

• add validate transformer (#3172) (b8771c1), closes #3121 #3125 #3129 #3130 #3132 #3134 #3149 #3150 #3157 #3165 #3167 #3171

1.18.8 (2025-02-07)

Bug Fixes

• bump ai-constructs to ^1.2.2 (#3141) (23519e3)

1.18.7 (2025-01-30)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.18.6 (2025-01-16)

Bug Fixes

• remove transitive dev dependencies from bundled jsii constructs (#3092) (f1243e2)

1.18.5 (2024-12-23)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.18.4 (2024-12-23)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.18.3 (2024-12-17)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.18.2 (2024-11-20)

Bug Fixes

• bump ai-constructs to ^1.0.0 (#3040) (0e9e195)

1.18.1 (2024-11-20)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.18.0 (2024-11-19)

Features

• bump conversation and generation transformers to v1 (#3030) (1d9e59e)

1.17.3 (2024-11-14)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.17.2 (2024-11-14)

Bug Fixes

• plumb outputStorageStrategy through conversation transformer to handler (#3017) (acc8140)

1.17.1 (2024-11-12)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.17.0 (2024-11-08)

Features

• add imported DDB tables for gen 2 migration in experimental state (#2992) (0c415b3)
• conversation: propagate errors from lambda to client (#3002) (141512b)
• conversation: support response streaming (#2986) (815d51f)

1.16.0 (2024-10-28)

Bug Fixes

• enable IAM auth for custom types (#2961) (#2971) (0e003d2)

Features

• add metrics metadata for auth mode and custom operations (#2966) (5571a90)
• get datasource map for migration (#2668) (02c7da0)
• import existing table to amplify managed table (#2634) (b3fb28f)

Reverts

• Revert "fix: enable IAM auth for custom types (#2961) (#2971)" (#2975) (8da7802), closes #2961 #2971 #2975
• Revert "feat: get datasource map for migration (#2668)" (#2907) (2b17871), closes #2668 #2907

1.15.1 (2024-10-17)

Bug Fixes

• enable IAM auth for custom types (#2961) (8fc24f3)

Reverts

• Revert "fix: enable IAM auth for custom types (#2961)" (#2964) (bd7484f), closes #2961 #2964

1.15.0 (2024-10-10)

Bug Fixes

• add aws_iam to custom operations when enableIamAuthorization is enabled; fix graphql type utils (#2921) (5cb5a2b)
• appsync ttl correct duration time unit in ms (#2928) (d690bfa)

Features

• conversation: per message items and lambda history retrieval pattern (#2914) (874a30a)

1.14.0 (2024-10-01)

Features

• exposing stack property for data construct (#2899) (48685dd)

1.13.0 (2024-09-16)

Features

• Add L1 construct properties to resources.graphqlApi (#2840) (f467967)

1.12.0 (2024-09-06)

Bug Fixes

• don't print deprecation warning when pattern is not used (#2816) (4c5fc2a)

Features

• conversation: add conversation transformer (#2827) (cee6aef)
• generation-transformer: add generation transformer (#2820) (a86db4e)

1.11.8 (2024-09-03)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.7 (2024-08-28)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.6 (2024-08-20)

Bug Fixes

• change gen 1 patterns to warning message instead of error (#2768) (97b1f36)

1.11.5 (2024-08-12)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.4 (2024-08-01)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.3 (2024-07-25)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.2 (2024-07-15)

Bug Fixes

• add translation behavior to disable gen 1 patterns (#2670) (38d1a71)

1.11.1 (2024-07-02)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.11.0 (2024-07-01)

Features

• support custom SSL certs in SQL lambda handler (#2631) (f444517)

1.10.0 (2024-06-25)

Features

• allow subscriptions to inherit primary model auth rules for relational fields behind a feature flag (#2649) (56a853a)

1.9.5 (2024-06-06)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.9.4 (2024-06-04)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.9.3 (2024-05-15)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.9.2 (2024-05-10)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.9.1 (2024-05-01)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.9.0 (2024-04-26)

Features

• allow multiple graphql APIs in a cdk app (#2406) (72ca6ba)
• api: enable cors on codegen asset bucket (#2366) (b69a492)
• generic iam authorization (#2385) (550ee80)
• support multiple connection Uris for SQL databases (#2481) (7ea8000)

1.8.1 (2024-04-16)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.8.0 (2024-04-11)

Bug Fixes

• propagate mutation context to relational fields (#2416) (fd7f6fb)

Features

• add cdk sql connection string support (#2409) (274d117)
• adds a default none data source (#2408) (98ae284)
• Fetch SNS topic ARN from SQL manifest (#2345) (fca256e)

1.7.0 (2024-03-28)

Features

• add secrets manager as credential store for sql lambda (#2289) (affdb98)

1.6.0 (2024-03-13)

Features

• expose table representative & access refactor for amplify managed table in api construct (8777cd1)
• replace conflictResolution with dataStoreConfiguration (#2298) (b5fb92b)

1.5.7 (2024-02-28)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.5.6 (2024-02-05)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.5.5 (2024-01-30)

Bug Fixes

• Use deployment rather than bucket for model schema URI (#2202) (3564898)

1.5.4 (2024-01-22)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.5.3 (2023-12-21)

Bug Fixes

• Fix manyToMany relationships with Amplify managed table strategies (#2151) (2dccaa6)

1.5.2 (2023-12-18)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.5.1 (2023-12-14)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.5.0 (2023-12-06)

Bug Fixes

• validate SSM paths in sql db connection config (#2118) (b9cd0d7)

Features

• combine heterogeneous data sources (#2109) (fd58bb5)
• Remove experimental flags; add missing API construct types (#2122) (a00f4dc)
• Support custom SQL across definitions (#2115) (eab4820)

1.4.3 (2023-11-22)

Bug Fixes

• Allow custom SQL statements without model declarations (#2087) (ea5b26c)

1.4.2 (2023-11-18)

Bug Fixes

• regionalize lambda layer patching SNS topics (#2079) (6006c86)

1.4.1 (2023-11-16)

Bug Fixes

• update backend-output-storage dependencies (#2075) (e577192)

1.4.0 (2023-11-15)

Bug Fixes

• address managed table QA feedbacks (#2059) (82a5cd6)
• Change 'rds' to 'sql' in public-facing symbols (#2069) (ff374dd)
• construct hub link image (dbc8ea3)
• fix api extract (1f5aa54)
• Make VPC configuration optional (#2021) (698d816)

Features

• add managed table support in API construct (#2024) (96a0d94), closes #1849 #1903 #1940 #1971 #1973
• add postgres engine and update types as needed (#1979) (5257d53)
• Add SQL database support to AmplifyGraphqlApi construct (#1986) (2ff63a5), closes #1917 #1983
• enable api definition to pass in referenced functions (#2061) (d281f5b)
• sql lambda provisioned concurrency (#2055) (d8c5bf0)
• transformer behavior of replacing table upon gsi updates (#2067) (c4b7530)

1.3.0 (2023-11-06)

Features

• enable allowListedRoles as string (#2016) (02b9cc0)

1.2.1 (2023-11-02)

Bug Fixes

• pass in and use correct lambda arn for lambdaauthorizers (#2007) (4114411)

1.2.0 (2023-10-27)

Features

• add apiId to AmplifyGraphqlApi construct properties (#1987) (ccc12f6)
• throw early exception if multiple instances exist in a single stack (#1990) (6dec41b)

1.1.5 (2023-10-21)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.1.4 (2023-10-12)

Bug Fixes

• optimize codegen asset upload (9e906d9)
• speed up codegen asset deployment (#1933) (67cfa6a)
• update readme and docs so they don't get overwritten (40bc411)

1.1.3 (2023-10-05)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.1.2 (2023-10-03)

Bug Fixes

• reference api id via context, not hard-coded logical id name (#1911) (538ddc3)

1.1.1 (2023-10-02)

Note: Version bump only for package @aws-amplify/graphql-api-construct

1.1.0 (2023-09-28)

Bug Fixes

• add missing jsdoc for construct constructor (19463f6)
• adding tests, and fixing some bugs, updating api a bit (4737b9f)
• api export for api construct (6395d84)
• don't perform sub if bucketName is an unresolved token (7750868)
• enable autoDeleteObjects on the codegen bucket (ba508a6)
• trigger republish of dependencies that failed in https://app.circleci.com/pipelines/github/aws-amplify/amplify-category-api/7981/workflows/e7366f04-6f0a-4ee4-9cc2-1772089e8005/jobs/163571 (f2c7151)
• update api extract (56fc360)
• update local deps after release (d6469f8)

Features

• add amplify metadata to stack description if none is provided (58266f1)
• add api properties without needing to drop into generated l1 resources (cb104df)
• add construct method to retrieve generated function slots (3952f47)
• add graphql api cdk construct (681939d)
• add model schema uri to outputs (b6ce89c)
• allow adding resolvers, functions, and data sources without leaving l3 (b0d9746)
• bump graphql construct to stable/v1 (#1876) (9f66e9c)
• bump major version of transformer packages (2458c84)
• disable amplify cfn outputs for cdk apps (0c72d18)
• enable jsii builds for the api construct (#1840) (f6e9aff)
• release alpha cdk construct (a6dc337)
• rename authorizationConfig into authorizationModes, and move adminRoles up (#1888) (7148814)
• store api id on stack output (#1801) (cd54115)
• store construct output (#1721) (472ba66)
• support custom preprocessors for different schema shapes (37a2814)

0.9.0 (2023-09-27)

Bug Fixes

• add missing jsdoc for construct constructor (19463f6)

Features

• add api properties without needing to drop into generated l1 resources (cb104df)
• allow adding resolvers, functions, and data sources without leaving l3 (b0d9746)
• rename authorizationConfig into authorizationModes, and move adminRoles up (#1888) (7148814)

0.8.0 (2023-09-20)

Features

• add amplify metadata to stack description if none is provided (58266f1)
• disable amplify cfn outputs for cdk apps (0c72d18)

0.7.1 (2023-09-14)

Note: Version bump only for package @aws-amplify/graphql-construct-alpha

0.7.0 (2023-09-13)

Bug Fixes

• update local deps after release (d6469f8)

Features

• enable jsii builds for the api construct (#1840) (f6e9aff)

0.6.2 (2023-09-07)

Bug Fixes

• enable autoDeleteObjects on the codegen bucket (ba508a6)

0.6.1 (2023-08-30)

Note: Version bump only for package @aws-amplify/graphql-construct-alpha

0.6.0 (2023-08-28)

Bug Fixes

• don't perform sub if bucketName is an unresolved token (7750868)

Features

• add model schema uri to outputs (b6ce89c)
• store api id on stack output (#1801) (cd54115)

0.5.0 (2023-08-09)

Bug Fixes

• api export for api construct (6395d84)

Features

• bump major version of transformer packages (2458c84)
• store construct output (#1721) (472ba66)

0.4.1 (2023-07-21)

Note: Version bump only for package @aws-amplify/graphql-construct-alpha

0.4.0 (2023-07-18)

Features

• support custom preprocessors for different schema shapes (37a2814)

0.3.3 (2023-07-17)

Note: Version bump only for package @aws-amplify/graphql-construct-alpha

0.3.2 (2023-07-07)

Note: Version bump only for package @aws-amplify/graphql-construct-alpha

0.3.1 (2023-07-07)

Bug Fixes

• trigger republish of dependencies that failed in https://app.circleci.com/pipelines/github/aws-amplify/amplify-category-api/7981/workflows/e7366f04-6f0a-4ee4-9cc2-1772089e8005/jobs/163571 (f2c7151)

0.3.0 (2023-07-07)

Features

• release alpha cdk construct (a6dc337)

0.2.0 (2023-06-29)

Bug Fixes

• adding tests, and fixing some bugs, updating api a bit (4737b9f)
• update api extract (56fc360)

Features

• add construct method to retrieve generated function slots (3952f47)
• add graphql api cdk construct (681939d)

0.1.0 (2023-06-20)

Bug Fixes

• update api extract (56fc360)

Features

• add graphql api cdk construct (681939d)