Syntax Properties Return values Examples See also

AWS::AppSync::GraphQLApi

The AWS::AppSync::GraphQLApi resource creates a new Amazon AppSync GraphQL API. This is the top-level construct for your application. For more information, see Quick Start in the Amazon AppSync Developer Guide.

Syntax

To declare this entity in your Amazon CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::AppSync::GraphQLApi",
  "Properties" : {
      "AdditionalAuthenticationProviders" : [ AdditionalAuthenticationProvider, ... ],
      "ApiType" : String,
      "AuthenticationType" : String,
      "EnhancedMetricsConfig" : EnhancedMetricsConfig,
      "EnvironmentVariables" : {Key: Value, ...},
      "IntrospectionConfig" : String,
      "LambdaAuthorizerConfig" : LambdaAuthorizerConfig,
      "LogConfig" : LogConfig,
      "MergedApiExecutionRoleArn" : String,
      "Name" : String,
      "OpenIDConnectConfig" : OpenIDConnectConfig,
      "OwnerContact" : String,
      "QueryDepthLimit" : Integer,
      "ResolverCountLimit" : Integer,
      "Tags" : [ Tag, ... ],
      "UserPoolConfig" : UserPoolConfig,
      "Visibility" : String,
      "XrayEnabled" : Boolean
    }
}

YAML


Type: AWS::AppSync::GraphQLApi
Properties:
  AdditionalAuthenticationProviders: 
    - AdditionalAuthenticationProvider
  ApiType: String
  AuthenticationType: String
  EnhancedMetricsConfig: 
    EnhancedMetricsConfig
  EnvironmentVariables: 
    Key: Value
  IntrospectionConfig: String
  LambdaAuthorizerConfig: 
    LambdaAuthorizerConfig
  LogConfig: 
    LogConfig
  MergedApiExecutionRoleArn: String
  Name: String
  OpenIDConnectConfig: 
    OpenIDConnectConfig
  OwnerContact: String
  QueryDepthLimit: Integer
  ResolverCountLimit: Integer
  Tags: 
    - Tag
  UserPoolConfig: 
    UserPoolConfig
  Visibility: String
  XrayEnabled: Boolean

Properties

AdditionalAuthenticationProviders

A list of additional authentication providers for the GraphqlApi API.

Required: No

Type: Array of AdditionalAuthenticationProvider

Update requires: No interruption

ApiType

The value that indicates whether the GraphQL API is a standard API (GRAPHQL) or merged API (MERGED).

WARNING: If the ApiType has not been defined, explicitly setting it to GRAPHQL in a template/stack update will result in an API replacement and new DNS values.

The following values are valid:

GRAPHQL | MERGED

Required: No

Type: String

Update requires: No interruption

AuthenticationType

Security configuration for your GraphQL API. For allowed values (such as API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT, or AWS_LAMBDA), see Security in the Amazon AppSync Developer Guide.

Required: Yes

Type: String

Update requires: No interruption

EnhancedMetricsConfig

Enables and controls the enhanced metrics feature. Enhanced metrics emit granular data on API usage and performance such as AppSync request and error counts, latency, and cache hits/misses. All enhanced metric data is sent to your CloudWatch account, and you can configure the types of data that will be sent.

Enhanced metrics can be configured at the resolver, data source, and operation levels. For more information, see Monitoring and logging in the Amazon AppSync User Guide.

Required: No

Type: EnhancedMetricsConfig

Update requires: No interruption

EnvironmentVariables

A map containing the list of resources with their properties and environment variables. For more information, see Environmental variables.

Pattern: ^[A-Za-z]+\\w*$\\

Minimum: 2

Maximum: 64

Required: No

Type: Object of String

Pattern: ^[A-Za-z]+\w*$

Update requires: No interruption

IntrospectionConfig

Sets the value of the GraphQL API to enable (ENABLED) or disable (DISABLED) introspection. If no value is provided, the introspection configuration will be set to ENABLED by default. This field will produce an error if the operation attempts to use the introspection feature while this field is disabled.

For more information about introspection, see GraphQL introspection.

Required: No

Type: String

Update requires: No interruption

LambdaAuthorizerConfig

A LambdaAuthorizerConfig holds configuration on how to authorize Amazon AppSync API access when using the AWS_LAMBDA authorizer mode. Be aware that an Amazon AppSync API may have only one Lambda authorizer configured at a time.

Required: No

Type: LambdaAuthorizerConfig

Update requires: No interruption

LogConfig

The Amazon CloudWatch Logs configuration.

Required: No

Type: LogConfig

Update requires: No interruption

MergedApiExecutionRoleArn

The Amazon Identity and Access Management service role ARN for a merged API. The AppSync service assumes this role on behalf of the Merged API to validate access to source APIs at runtime and to prompt the AUTO_MERGE to update the merged API endpoint with the source API changes automatically.

Required: No

Type: String

Update requires: No interruption

Name

The API name.

Required: Yes

Type: String

Update requires: No interruption

OpenIDConnectConfig

The OpenID Connect configuration.

Required: No

Type: OpenIDConnectConfig

Update requires: No interruption

OwnerContact

The owner contact information for an API resource.

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

Required: No

Type: String

Update requires: No interruption

QueryDepthLimit

The maximum depth a query can have in a single request. Depth refers to the amount of nested levels allowed in the body of query. The default value is 0 (or unspecified), which indicates there's no depth limit. If you set a limit, it can be between 1 and 75 nested levels. This field will produce a limit error if the operation falls out of bounds. Note that fields can still be set to nullable or non-nullable. If a non-nullable field produces an error, the error will be thrown upwards to the first nullable field available.

Required: No

Type: Integer

Update requires: No interruption

ResolverCountLimit

The maximum number of resolvers that can be invoked in a single request. The default value is 0 (or unspecified), which will set the limit to 10000. When specified, the limit value can be between 1 and 10000. This field will produce a limit error if the operation falls out of bounds.

Required: No

Type: Integer

Update requires: No interruption

Tags

An arbitrary set of tags (key-value pairs) for this GraphQL API.

Required: No

Type: Array of Tag

Update requires: No interruption

UserPoolConfig

Optional authorization configuration for using Amazon Cognito user pools with your GraphQL endpoint.

Required: No

Type: UserPoolConfig

Update requires: No interruption

Visibility

Sets the scope of the GraphQL API to public (GLOBAL) or private (PRIVATE). By default, the scope is set to Global if no value is provided.

WARNING: If Visibility has not been defined, explicitly setting it to GLOBAL in a template/stack update will result in an API replacement and new DNS values.

Required: No

Type: String

Update requires: No interruption

XrayEnabled

A flag indicating whether to use Amazon X-Ray tracing for this GraphqlApi.

Required: No

Type: Boolean

Update requires: No interruption

Return values

Ref

When you pass the logical ID of an AWS::AppSync::GraphQLApi resource to the intrinsic Ref function, the function returns the ARN of the GraphQL API, such as arn:aws:appsync:us-east-1:123456789012:apis/graphqlapiid.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using Fn::GetAtt, see Fn::GetAtt.

ApiId: Unique Amazon AppSync GraphQL API identifier.
Arn: The Amazon Resource Name (ARN) of the API key, such as arn:aws:appsync:us-east-1:123456789012:apis/graphqlapiid.
GraphQLDns: The fully qualified domain name (FQDN) of the endpoint URL of your GraphQL API.
GraphQLEndpointArn: The GraphQL endpoint ARN.
GraphQLUrl: The Endpoint URL of your GraphQL API.
RealtimeDns: The fully qualified domain name (FQDN) of the real-time endpoint URL of your GraphQL API.
RealtimeUrl: The GraphQL API real-time endpoint URL. For more information, see Discovering the real-time endpoint from the GraphQL endpoint.

Examples

GraphQL API Creation Example

The following example creates a GraphQL API.

YAML


Parameters:
  graphQlApiName:
    Type: String
  userPoolId:
    Type: String
  userPoolAwsRegion:
    Type: String
  defaultAction:
    Type: String
Resources:
  GraphQLApi:
    Type: AWS::AppSync::GraphQLApi
    Properties:
      Name:
	Ref: graphQlApiName
      AuthenticationType: "AMAZON_COGNITO_USER_POOLS"
      UserPoolConfig:
        UserPoolId:
          Ref: userPoolId
        AwsRegion:
          Ref: userPoolAwsRegion
        DefaultAction:
          Ref: defaultAction

JSON


{
  "Parameters": {
    "graphQlApiName": {
      "Type": "String"
    },
    "userPoolId": {
      "Type": "String"
    },
    "userPoolAwsRegion": {
      "Type": "String"
    },
    "defaultAction": {
      "Type": "String"
    }
  },
  "Resources": {
    "GraphQLApi": {
      "Type": "AWS::AppSync::GraphQLApi",
      "Properties": {
        "Name": {
          "Ref": "graphQlApiName"
        },
        "AuthenticationType": "AMAZON_COGNITO_USER_POOLS",
        "UserPoolConfig": {
          "UserPoolId": {
            "Ref": "userPoolId"
          },
          "AwsRegion": {
            "Ref": "userPoolAwsRegion"
          },
          "DefaultAction": {
            "Ref": "defaultAction"
          }
        }
      }
    }
  }
}