class GraphqlApi (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.AppSync.GraphqlApi`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awsappsync#GraphqlApi`
Java	`software.amazon.awscdk.services.appsync.GraphqlApi`
Python	`aws_cdk.aws_appsync.GraphqlApi`
TypeScript (source)	`aws-cdk-lib` » `aws_appsync` » `GraphqlApi`

Implements IConstruct, IDependable, IResource, IGraphqlApi

An AppSync GraphQL API.

Example

import * as events from 'aws-cdk-lib/aws-events';

const api = new appsync.GraphqlApi(this, 'EventBridgeApi', {
  name: 'EventBridgeApi',
  definition: appsync.Definition.fromFile(path.join(__dirname, 'appsync.eventbridge.graphql')),
});

const bus = new events.EventBus(this, 'DestinationEventBus', {});

const dataSource = api.addEventBridgeDataSource('NoneDS', bus);

dataSource.createResolver('EventResolver', {
  typeName: 'Mutation',
  fieldName: 'emitEvent',
  requestMappingTemplate: appsync.MappingTemplate.fromFile('request.vtl'),
  responseMappingTemplate: appsync.MappingTemplate.fromFile('response.vtl'),
});

Initializer

new GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps)

Parameters

scope Construct
id string
props GraphqlApiProps

Construct Props

Name	Type	Description
name	`string`	the name of the GraphQL API.
authorizationConfig?	`AuthorizationConfig`	Optional authorization configuration.
definition?	`Definition`	Definition (schema file or source APIs) for this GraphQL Api.
domainName?	`DomainOptions`	The domain name configuration for the GraphQL API.
environmentVariables?	`{ [string]: string }`	A map containing the list of resources with their properties and environment variables.
introspectionConfig?	`IntrospectionConfig`	A value indicating whether the API to enable (ENABLED) or disable (DISABLED) introspection.
logConfig?	`LogConfig`	Logging configuration for this api.
ownerContact?	`string`	The owner contact information for an API resource.
queryDepthLimit?	`number`	A number indicating the maximum depth resolvers should be accepted when handling queries.
resolverCountLimit?	`number`	A number indicating the maximum number of resolvers that should be accepted when handling queries.
schema?⚠️	`ISchema`	GraphQL schema definition. Specify how you want to define your schema.
visibility?	`Visibility`	A value indicating whether the API is accessible from anywhere (GLOBAL) or can only be access from a VPC (PRIVATE).
xrayEnabled?	`boolean`	A flag indicating whether or not X-Ray tracing is enabled for the GraphQL API.

name

Type: string

the name of the GraphQL API.

authorizationConfig?

Type: AuthorizationConfig (optional, default: API Key authorization)

Optional authorization configuration.

definition?

Type: Definition (optional)

Definition (schema file or source APIs) for this GraphQL Api.

domainName?

Type: DomainOptions (optional, default: no domain name)

The domain name configuration for the GraphQL API.

The Route 53 hosted zone and CName DNS record must be configured in addition to this setting to enable custom domain URL

environmentVariables?

Type: { [string]: string } (optional, default: No environment variables.)

A map containing the list of resources with their properties and environment variables.

There are a few rules you must follow when creating keys and values:

Keys must begin with a letter.
Keys must be between 2 and 64 characters long.
Keys can only contain letters, numbers, and the underscore character (_).
Values can be up to 512 characters long.
You can configure up to 50 key-value pairs in a GraphQL API.

introspectionConfig?

Type: IntrospectionConfig (optional, default: IntrospectionConfig.ENABLED)

A value indicating whether the API to enable (ENABLED) or disable (DISABLED) introspection.

logConfig?

Type: LogConfig (optional, default: None)

Logging configuration for this api.

ownerContact?

Type: string (optional, default: No owner contact.)

The owner contact information for an API resource.

This field accepts any string input with a length of 0 - 256 characters.

queryDepthLimit?

Type: number (optional, default: The default value is 0 (or unspecified) which indicates no maximum depth.)

A number indicating the maximum depth resolvers should be accepted when handling queries.

Value must be withing range of 0 to 75

resolverCountLimit?

Type: number (optional, default: The default value is 0 (or unspecified), which will set the limit to 10000)

A number indicating the maximum number of resolvers that should be accepted when handling queries.

Value must be withing range of 0 to 10000

schema?⚠️

⚠️ Deprecated: use Definition.schema instead

Type: ISchema (optional, default: schema will be generated code-first (i.e. addType, addObjectType, etc.))

GraphQL schema definition. Specify how you want to define your schema.

SchemaFile.fromAsset(filePath: string) allows schema definition through schema.graphql file

visibility?

Type: Visibility (optional, default: GLOBAL)

A value indicating whether the API is accessible from anywhere (GLOBAL) or can only be access from a VPC (PRIVATE).

xrayEnabled?

Type: boolean (optional, default: false)

A flag indicating whether or not X-Ray tracing is enabled for the GraphQL API.

Properties

Name	Type	Description
apiId	`string`	an unique AWS AppSync GraphQL API identifier i.e. 'lxz775lwdrgcndgz3nurvac7oa'.
appSyncDomainName	`string`	The AppSyncDomainName of the associated custom domain.
arn	`string`	the ARN of the API.
env	`ResourceEnvironment`	The environment this resource belongs to.
graphQLEndpointArn	`string`	The GraphQL endpoint ARN.
graphqlUrl	`string`	the URL of the endpoint created by AppSync.
logGroup	`ILogGroup`	the CloudWatch Log Group for this API.
modes	`AuthorizationType[]`	The Authorization Types for this GraphQL Api.
name	`string`	the name of the API.
node	`Node`	The tree node.
schema	`ISchema`	the schema attached to this api (only available for GraphQL APIs, not available for merged APIs).
stack	`Stack`	The stack in which this resource is defined.
visibility	`Visibility`	the visibility of the API.
apiKey?	`string`	the configured API key, if present.

apiId

Type: string

an unique AWS AppSync GraphQL API identifier i.e. 'lxz775lwdrgcndgz3nurvac7oa'.

appSyncDomainName

Type: string

The AppSyncDomainName of the associated custom domain.

arn

Type: string

the ARN of the API.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

graphQLEndpointArn

Type: string

The GraphQL endpoint ARN.

graphqlUrl

Type: string

the URL of the endpoint created by AppSync.

logGroup

Type: ILogGroup

the CloudWatch Log Group for this API.

modes

Type: AuthorizationType[]

The Authorization Types for this GraphQL Api.

name

Type: string

the name of the API.

node

Type: Node

The tree node.

schema

Type: ISchema

the schema attached to this api (only available for GraphQL APIs, not available for merged APIs).

stack

Type: Stack

The stack in which this resource is defined.

visibility

Type: Visibility

the visibility of the API.

apiKey?

Type: string (optional, default: no api key)

the configured API key, if present.

Methods

Name	Description
addDynamoDbDataSource(id, table, options?)	add a new DynamoDB data source to this API.
addElasticsearchDataSource(id, domain, options?)⚠️	add a new elasticsearch data source to this API.
addEnvironmentVariable(key, value)	Add an environment variable to the construct.
addEventBridgeDataSource(id, eventBus, options?)	Add an EventBridge data source to this api.
addHttpDataSource(id, endpoint, options?)	add a new http data source to this API.
addLambdaDataSource(id, lambdaFunction, options?)	add a new Lambda data source to this API.
addNoneDataSource(id, options?)	add a new dummy data source to this API.
addOpenSearchDataSource(id, domain, options?)	add a new OpenSearch data source to this API.
addRdsDataSource(id, serverlessCluster, secretStore, databaseName?, options?)	add a new Rds data source to this API.
addRdsDataSourceV2(id, serverlessCluster, secretStore, databaseName?, options?)	add a new Rds data source to this API.
addSchemaDependency(construct)	Add schema dependency to a given construct.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
createResolver(id, props)	creates a new resolver for this datasource and API using the given properties.
grant(grantee, resources, ...actions)	Adds an IAM policy statement associated with this GraphQLApi to an IAM principal's policy.
grantMutation(grantee, ...fields)	Adds an IAM policy statement for Mutation access to this GraphQLApi to an IAM principal's policy.
grantQuery(grantee, ...fields)	Adds an IAM policy statement for Query access to this GraphQLApi to an IAM principal's policy.
grantSubscription(grantee, ...fields)	Adds an IAM policy statement for Subscription access to this GraphQLApi to an IAM principal's policy.
toString()	Returns a string representation of this construct.
static fromGraphqlApiAttributes(scope, id, attrs)	Import a GraphQL API through this function.

addDynamoDbDataSource(id, table, options?)

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

Parameters

id string — The data source's id.
table ITable — The DynamoDB table backing this data source.
options DataSourceOptions — The optional configuration for this data source.

Returns

DynamoDbDataSource

add a new DynamoDB data source to this API.

addElasticsearchDataSource(id, domain, options?)⚠️

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

⚠️ Deprecated: - use addOpenSearchDataSource

Parameters

id string — The data source's id.
domain IDomain — The elasticsearch domain for this data source.
options DataSourceOptions — The optional configuration for this data source.

Returns

ElasticsearchDataSource

add a new elasticsearch data source to this API.

addEnvironmentVariable(key, value)

public addEnvironmentVariable(key: string, value: string): void

Parameters

key string
value string

Add an environment variable to the construct.

addEventBridgeDataSource(id, eventBus, options?)

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

Parameters

id string — The data source's id.
eventBus IEventBus — The EventBridge EventBus on which to put events.
options DataSourceOptions — The optional configuration for this data source.

Returns

EventBridgeDataSource

Add an EventBridge data source to this api.

addHttpDataSource(id, endpoint, options?)

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

Parameters

id string — The data source's id.
endpoint string — The http endpoint.
options HttpDataSourceOptions — The optional configuration for this data source.

Returns

HttpDataSource

add a new http data source to this API.

addLambdaDataSource(id, lambdaFunction, options?)

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

Parameters

id string — The data source's id.
lambdaFunction IFunction — The Lambda function to call to interact with this data source.
options DataSourceOptions — The optional configuration for this data source.

Returns

LambdaDataSource

add a new Lambda data source to this API.

addNoneDataSource(id, options?)

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

Parameters

id string — The data source's id.
options DataSourceOptions — The optional configuration for this data source.

Returns

NoneDataSource

add a new dummy data source to this API.

Useful for pipeline resolvers and for backend changes that don't require a data source.

addOpenSearchDataSource(id, domain, options?)

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

Parameters

id string — The data source's id.
domain IDomain — The OpenSearch domain for this data source.
options DataSourceOptions — The optional configuration for this data source.

Returns

OpenSearchDataSource

add a new OpenSearch data source to this API.

addRdsDataSource(id, serverlessCluster, secretStore, databaseName?, options?)

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

Parameters

id string — The data source's id.
serverlessCluster IServerlessCluster — The serverless cluster to interact with this data source.
secretStore ISecret — The secret store that contains the username and password for the serverless cluster.
databaseName string — The optional name of the database to use within the cluster.
options DataSourceOptions — The optional configuration for this data source.

Returns

RdsDataSource

add a new Rds data source to this API.

addRdsDataSourceV2(id, serverlessCluster, secretStore, databaseName?, options?)

public addRdsDataSourceV2(id: string, serverlessCluster: IDatabaseCluster, secretStore: ISecret, databaseName?: string, options?: DataSourceOptions): RdsDataSource

Parameters

id string — The data source's id.
serverlessCluster IDatabaseCluster — The serverless V2 cluster to interact with this data source.
secretStore ISecret — The secret store that contains the username and password for the serverless cluster.
databaseName string — The optional name of the database to use within the cluster.
options DataSourceOptions — The optional configuration for this data source.

Returns

RdsDataSource

add a new Rds data source to this API.

addSchemaDependency(construct)

public addSchemaDependency(construct: CfnResource): boolean

Parameters

construct CfnResource — the dependee.

Returns

boolean

Add schema dependency to a given construct.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

createResolver(id, props)

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

Parameters

id string
props ExtendedResolverProps

Returns

Resolver

creates a new resolver for this datasource and API using the given properties.

grant(grantee, resources, ...actions)

public grant(grantee: IGrantable, resources: IamResource, ...actions: string[]): Grant

Parameters

grantee IGrantable — The principal.
resources IamResource — The set of resources to allow (i.e. ...:[region]:[accountId]:apis/GraphQLId/...).
actions string — The actions that should be granted to the principal (i.e. appsync:graphql ).

Returns

Grant

Adds an IAM policy statement associated with this GraphQLApi to an IAM principal's policy.

grantMutation(grantee, ...fields)

public grantMutation(grantee: IGrantable, ...fields: string[]): Grant

Parameters

grantee IGrantable — The principal.
fields string — The fields to grant access to that are Mutations (leave blank for all).

Returns

Grant

Adds an IAM policy statement for Mutation access to this GraphQLApi to an IAM principal's policy.

grantQuery(grantee, ...fields)

public grantQuery(grantee: IGrantable, ...fields: string[]): Grant

Parameters

grantee IGrantable — The principal.
fields string — The fields to grant access to that are Queries (leave blank for all).

Returns

Grant

Adds an IAM policy statement for Query access to this GraphQLApi to an IAM principal's policy.

grantSubscription(grantee, ...fields)

public grantSubscription(grantee: IGrantable, ...fields: string[]): Grant

Parameters

grantee IGrantable — The principal.
fields string — The fields to grant access to that are Subscriptions (leave blank for all).

Returns

Grant

Adds an IAM policy statement for Subscription access to this GraphQLApi to an IAM principal's policy.

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

static fromGraphqlApiAttributes(scope, id, attrs)

public static fromGraphqlApiAttributes(scope: Construct, id: string, attrs: GraphqlApiAttributes): IGraphqlApi

Parameters

scope Construct — scope.
id string — id.
attrs GraphqlApiAttributes — GraphQL API Attributes of an API.

Returns

IGraphqlApi

Import a GraphQL API through this function.