# GraphqlApi

An AppSync GraphQL API.

Extends: Construct › Resource › GraphqlApiBase › GraphqlApi
Implements: IResource, IGraphqlApi, IEnvironmentAware, IGraphQLApiRef, IConstruct, IDependable

- CloudFormation: [`AWS::AppSync::GraphQLApi`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-appsync-graphqlapi.html)
- L1 type: [`CfnGraphQLApi`](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.CfnGraphQLApi.html)
- Source: [`aws-appsync/lib/graphqlapi.ts`](https://github.com/aws/aws-cdk/blob/v2.274.0/packages/aws-cdk-lib/aws-appsync/lib/graphqlapi.ts#L588)
- Type last changed: v2.196.0 · 16 May 2025

## Example

```ts
const schema = new appsync.SchemaFile({ filePath: 'mySchemaFile' })
new appsync.GraphqlApi(this, 'api', {
  name: 'myApi',
  definition: appsync.Definition.fromSchema(schema),
  enhancedMetricsConfig: {
    dataSourceLevelMetricsBehavior: appsync.DataSourceLevelMetricsBehavior.FULL_REQUEST_DATA_SOURCE_METRICS,
    operationLevelMetricsConfig: appsync.OperationLevelMetricsConfig.ENABLED,
    resolverLevelMetricsBehavior: appsync.ResolverLevelMetricsBehavior.FULL_REQUEST_RESOLVER_METRICS,
  },
});
```

## Initializer

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

## Construct Props

- `authorizationConfig`: [AuthorizationConfig](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.AuthorizationConfig.html) — Optional authorization configuration.

  **Default:** API Key authorization

- `definition`: [Definition](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.Definition.html) — Definition (schema file or source APIs) for this GraphQL Api.

- `domainName`: [DomainOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.DomainOptions.html) — The domain name configuration for the GraphQL API.

  **Default:** no domain name

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

- `enhancedMetricsConfig`: [EnhancedMetricsConfig](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.EnhancedMetricsConfig.html) — Enables and controls the enhanced metrics feature.

  **Default:** Enhanced metrics disabled.

- `environmentVariables`: { [key: string]: string } — A map containing the list of resources with their properties and environment variables.

  **Default:** No 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`: [IntrospectionConfig](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.IntrospectionConfig.html) = IntrospectionConfig.ENABLED — A value indicating whether the API to enable (ENABLED) or disable (DISABLED) introspection.

- `logConfig`: [LogConfig](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.LogConfig.html) = None — Logging configuration for this api.

- `name`: string (required) — the name of the GraphQL API.

- `ownerContact`: string — The owner contact information for an API resource.

  **Default:** No owner contact.

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

- `queryDepthLimit`: number — A number indicating the maximum depth resolvers should be accepted when handling queries.

  **Default:** The default value is 0 (or unspecified) which indicates no maximum depth.

  Value must be withing range of 0 to 75

- `resolverCountLimit`: number — A number indicating the maximum number of resolvers that should be accepted when handling queries.

  **Default:** The default value is 0 (or unspecified), which will set the limit to 10000

  Value must be withing range of 0 to 10000

- `schema`: [ISchema](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.ISchema.html) — use Definition.schema instead

  **Default:** schema will be generated code-first (i.e. addType, addObjectType, etc.)

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

- `visibility`: [Visibility](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.Visibility.html) = GLOBAL — A value indicating whether the API is accessible from anywhere (GLOBAL) or can only be access from a VPC (PRIVATE).

- `xrayEnabled`: boolean = false — A flag indicating whether or not X-Ray tracing is enabled for the GraphQL API.

## Properties

- `apiId`: string (required) — a unique AWS AppSync GraphQL API identifier i.e. 'lxz775lwdrgcndgz3nurvac7oa'.

- `apiKey`: string — the configured API key, if present.

  **Default:** no api key

- `appSyncDomainName`: string (required) — The AppSyncDomainName of the associated custom domain.

- `arn`: string (required) — the ARN of the API.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) (required) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `graphQlApiRef`: [GraphQLApiReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_appsync.GraphQLApiReference.html) (required) — A reference to a GraphQLApi resource.

- `graphQLEndpointArn`: string (required) — The GraphQL endpoint ARN.

- `graphqlUrl`: string (required) — the URL of the endpoint created by AppSync.

- `logGroup`: [ILogGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.ILogGroup.html) (required) — the CloudWatch Log Group for this API.

- `modes`: [AuthorizationType](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.AuthorizationType.html)[] (required) — The Authorization Types for this GraphQL Api.

- `name`: string (required) — the name of the API.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) (required) — The tree node.

- `PROPERTY_INJECTION_ID`: string (required) (static) — Uniquely identifies this class.

- `schema`: [ISchema](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.ISchema.html) (required) — the schema attached to this api (only available for GraphQL APIs, not available for merged APIs).

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) (required) — The stack in which this resource is defined.

- `visibility`: [Visibility](/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.Visibility.html) (required) — the visibility of the API.

## Methods

- `addDynamoDbDataSource(id: string, table: ITable, options?: DataSourceOptions): DynamoDbDataSource` — add a new DynamoDB data source to this API.

  **Parameters**

  - `id` — The data source's id.
  - `table` — The DynamoDB table backing this data source.
  - `options` — The optional configuration for this data source.

- `addElasticsearchDataSource(id: string, domain: IDomain, options?: DataSourceOptions): ElasticsearchDataSource` — - use `addOpenSearchDataSource`

  **Parameters**

  - `id` — The data source's id.
  - `domain` — The elasticsearch domain for this data source.
  - `options` — The optional configuration for this data source.

- `addEnvironmentVariable(key: string, value: string): void` — Add an environment variable to the construct.

- `addEventBridgeDataSource(id: string, eventBus: IEventBus, options?: DataSourceOptions): EventBridgeDataSource` — Add an EventBridge data source to this api.

  **Parameters**

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

- `addHttpDataSource(id: string, endpoint: string, options?: HttpDataSourceOptions): HttpDataSource` — add a new http data source to this API.

  **Parameters**

  - `id` — The data source's id.
  - `endpoint` — The http endpoint.
  - `options` — The optional configuration for this data source.

- `addLambdaDataSource(id: string, lambdaFunction: IFunction, options?: DataSourceOptions): LambdaDataSource` — add a new Lambda data source to this API.

  **Parameters**

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

- `addNoneDataSource(id: string, options?: DataSourceOptions): 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.

  **Parameters**

  - `id` — The data source's id.
  - `options` — The optional configuration for this data source.

- `addOpenSearchDataSource(id: string, domain: IDomain, options?: DataSourceOptions): OpenSearchDataSource` — add a new OpenSearch data source to this API.

  **Parameters**

  - `id` — The data source's id.
  - `domain` — The OpenSearch domain for this data source.
  - `options` — The optional configuration for this data source.

- `addRdsDataSource(id: string, serverlessCluster: IServerlessCluster, secretStore: ISecret, databaseName?: string, options?: DataSourceOptions): RdsDataSource` — add a new Rds data source to this API.

  **Parameters**

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

- `addRdsDataSourceV2(id: string, serverlessCluster: IDatabaseCluster, secretStore: ISecret, databaseName?: string, options?: DataSourceOptions): RdsDataSource` — add a new Rds data source to this API.

  **Parameters**

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

- `addSchemaDependency(construct: CfnResource): boolean` — Add schema dependency to a given construct.

  **Parameters**

  - `construct` — the dependee.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — 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: string, props: ExtendedResolverProps): Resolver` — creates a new resolver for this datasource and API using the given properties.

- `fromGraphqlApiAttributes(scope: Construct, id: string, attrs: GraphqlApiAttributes): IGraphqlApi` (static) — Import a GraphQL API through this function.

  **Parameters**

  - `scope` — scope.
  - `id` — id.
  - `attrs` — GraphQL API Attributes of an API.

- `grant(grantee: IGrantable, resources: IamResource, ...actions: string[]): Grant` — Adds an IAM policy statement associated with this GraphQLApi to an IAM principal's policy.

  [disable-awslint:no-grants]

  **Parameters**

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

- `grantMutation(grantee: IGrantable, ...fields: string[]): Grant` — Adds an IAM policy statement for Mutation access to this GraphQLApi to an IAM principal's policy.

  [disable-awslint:no-grants]

  **Parameters**

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

- `grantQuery(grantee: IGrantable, ...fields: string[]): Grant` — Adds an IAM policy statement for Query access to this GraphQLApi to an IAM principal's policy.

  [disable-awslint:no-grants]

  **Parameters**

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

- `grantSubscription(grantee: IGrantable, ...fields: string[]): Grant` — Adds an IAM policy statement for Subscription access to this GraphQLApi to an IAM principal's policy.

  [disable-awslint:no-grants]

  **Parameters**

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

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.