AWS::Serverless::GraphQLApi
Use the Amazon Serverless Application Model (Amazon SAM) AWS::Serverless::GraphQLApi
resource type to create
and configure an Amazon AppSync GraphQL API for your serverless application.
To learn more about Amazon AppSync, see What is Amazon AppSync? in the Amazon AppSync Developer Guide.
Syntax
YAML
LogicalId
: Type: AWS::Serverless::GraphQLApi Properties: ApiKeys:ApiKeys
Auth:Auth
Cache:AWS::AppSync::ApiCache
DataSources:DataSource
DomainName:AWS::AppSync::DomainName
Functions:Function
Logging:LogConfig
Name:String
Resolvers:Resolver
SchemaInline:String
SchemaUri:String
Tags:- Tag
XrayEnabled:Boolean
Properties
ApiKeys
-
Create a unique key that can be used to perform GraphQL operations requiring an API key.
Type: ApiKeys
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn’t have an Amazon CloudFormation equivalent.
Auth
-
Configure authentication for your GraphQL API.
Type: Auth
Required: Yes
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn’t have an Amazon CloudFormation equivalent.
Cache
-
The input of a
CreateApiCache
operation.Type: AWS::AppSync::ApiCache
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the AWS::AppSync::ApiCache resource.
DataSources
-
Create data sources for functions in Amazon AppSync to connect to. Amazon SAM supports Amazon DynamoDB and Amazon Lambda data sources.
Type: DataSource
Required: Yes
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn’t have an Amazon CloudFormation equivalent.
DomainName
-
Custom domain name for your GraphQL API.
Type: AWS::AppSync::DomainName
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the AWS::AppSync::DomainName resource. Amazon SAM automatically generates the AWS::AppSync::DomainNameApiAssociation resource.
Functions
-
Configure functions in GraphQL APIs to perform certain operations.
Type: Function
Required: Yes
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn’t have an Amazon CloudFormation equivalent.
Logging
-
Configures Amazon CloudWatch logging for your GraphQL API.
If you don’t specify this property, Amazon SAM will generate
CloudWatchLogsRoleArn
and set the following values:-
ExcludeVerboseContent: true
-
FieldLogLevel: ALL
To opt out of logging, specify the following:
Logging: false
Type: LogConfig
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
LogConfig
property of anAWS::AppSync::GraphQLApi
resource. -
LogicalId
-
The unique name of your GraphQL API.
Type: String
Required: Yes
Amazon CloudFormation compatibility: This property is passed directly to the
Name
property of anAWS::AppSync::GraphQLApi
resource. Name
-
The name of your GraphQL API. Specify this property to override the
LogicalId
value.Type: String
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
Name
property of anAWS::AppSync::GraphQLApi
resource. Resolvers
-
Configure resolvers for the fields of your GraphQL API. Amazon SAM supports JavaScript pipeline resolvers.
Type: Resolver
Required: Yes
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn’t have an Amazon CloudFormation equivalent.
SchemaInline
-
The text representation of a GraphQL schema in SDL format.
Type: String
Required: Conditional. You must specify
SchemaInline
orSchemaUri
.Amazon CloudFormation compatibility: This property is passed directly to the
Definition
property of anAWS::AppSync::GraphQLSchema
resource. SchemaUri
-
The schema’s Amazon Simple Storage Service (Amazon S3) bucket URI or path to a local folder.
If you specify a path to a local folder, Amazon CloudFormation requires that the file is first uploaded to Amazon S3 before deployment. You can use the Amazon SAM CLI to facilitate this process. For more information, see Using the Amazon SAM CLI to upload local files at deployment.
Type: String
Required: Conditional. You must specify
SchemaInline
orSchemaUri
.Amazon CloudFormation compatibility: This property is passed directly to the
DefinitionS3Location
property of anAWS::AppSync::GraphQLSchema
resource. -
Tags (key-value pairs) for this GraphQL API. Use tags to identify and categorize resources.
Type: List of Tag
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
Tag
property of anAWS::AppSync::GraphQLApi
resource. XrayEnabled
-
Indicate whether to use Amazon X-Ray tracing for this resource.
Type: Boolean
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
XrayEnabled
property of anAWS::AppSync::GraphQLApi
resource.
Examples
GraphQL API with DynamoDB data source
In this example, we create a GraphQL API that uses a DynamoDB table as a data source.
schema.graphql
schema { query: Query mutation: Mutation } type Query { getPost(id: String!): Post } type Mutation { addPost(author: String!, title: String!, content: String!): Post! } type Post { id: String! author: String title: String content: String ups: Int! downs: Int! version: Int! }
template.yaml
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: DynamoDBPostsTable: Type: AWS::Serverless::SimpleTable MyGraphQLAPI: Type: AWS::Serverless::GraphQLApi Properties: SchemaUri: ./sam_graphql_api/schema.graphql Auth: Type: AWS_IAM DataSources: DynamoDb: PostsDataSource: TableName: !Ref DynamoDBPostsTable TableArn: !GetAtt DynamoDBPostsTable.Arn Functions: preprocessPostItem: Runtime: Name: APPSYNC_JS Version: 1.0.0 DataSource: NONE CodeUri: ./sam_graphql_api/preprocessPostItem.js createPostItem: Runtime: Name: APPSYNC_JS Version: "1.0.0" DataSource: PostsDataSource CodeUri: ./sam_graphql_api/createPostItem.js getPostFromTable: Runtime: Name: APPSYNC_JS Version: "1.0.0" DataSource: PostsDataSource CodeUri: ./sam_graphql_api/getPostFromTable.js Resolvers: Mutation: addPost: Runtime: Name: APPSYNC_JS Version: "1.0.0" Pipeline: - preprocessPostItem - createPostItem Query: getPost: CodeUri: ./sam_graphql_api/getPost.js Runtime: Name: APPSYNC_JS Version: "1.0.0" Pipeline: - getPostFromTable
createPostItem.js
import { util } from "@aws-appsync/utils"; export function request(ctx) { const { key, values } = ctx.prev.result; return { operation: "PutItem", key: util.dynamodb.toMapValues(key), attributeValues: util.dynamodb.toMapValues(values), }; } export function response(ctx) { return ctx.result; }
getPostFromTable.js
import { util } from "@aws-appsync/utils"; export function request(ctx) { return dynamoDBGetItemRequest({ id: ctx.args.id }); } export function response(ctx) { return ctx.result; } /** * A helper function to get a DynamoDB item */ function dynamoDBGetItemRequest(key) { return { operation: "GetItem", key: util.dynamodb.toMapValues(key), }; }
preprocessPostItem.js
import { util } from "@aws-appsync/utils"; export function request(ctx) { const id = util.autoId(); const { ...values } = ctx.args; values.ups = 1; values.downs = 0; values.version = 1; return { payload: { key: { id }, values: values } }; } export function response(ctx) { return ctx.result; }
Here is our resolver code:
getPost.js
export function request(ctx) { return {}; } export function response(ctx) { return ctx.prev.result; }
GraphQL API with a Lambda function as a data source
In this example, we create a GraphQL API that uses a Lambda function as a data source.
template.yaml
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: MyLambdaFunction: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: nodejs20.x CodeUri: ./lambda MyGraphQLAPI: Type: AWS::Serverless::GraphQLApi Properties: Name: MyApi SchemaUri: ./gql/schema.gql Auth: Type: API_KEY ApiKeys: MyApiKey: Description: my api key DataSources: Lambda: MyLambdaDataSource: FunctionArn: !GetAtt MyLambdaFunction.Arn Functions: lambdaInvoker: Runtime: Name: APPSYNC_JS Version: 1.0.0 DataSource: MyLambdaDataSource CodeUri: ./gql/invoker.js Resolvers: Mutation: addPost: Runtime: Name: APPSYNC_JS Version: 1.0.0 Pipeline: - lambdaInvoker Query: getPost: Runtime: Name: APPSYNC_JS Version: 1.0.0 Pipeline: - lambdaInvoker Outputs: MyGraphQLAPI: Description: AppSync API Value: !GetAtt MyGraphQLAPI.GraphQLUrl MyGraphQLAPIMyApiKey: Description: API Key for authentication Value: !GetAtt MyGraphQLAPIMyApiKey.ApiKey
schema.graphql
schema { query: Query mutation: Mutation } type Query { getPost(id: ID!): Post } type Mutation { addPost(id: ID!, author: String!, title: String, content: String): Post! } type Post { id: ID! author: String! title: String content: String ups: Int downs: Int }
Here are our functions:
lambda/index.js
exports.handler = async (event) => { console.log("Received event {}", JSON.stringify(event, 3)); const posts = { 1: { id: "1", title: "First book", author: "Author1", content: "Book 1 has this content", ups: "100", downs: "10", }, }; console.log("Got an Invoke Request."); let result; switch (event.field) { case "getPost": return posts[event.arguments.id]; case "addPost": // return the arguments back return event.arguments; default: throw new Error("Unknown field, unable to resolve " + event.field); } };
invoker.js
import { util } from "@aws-appsync/utils"; export function request(ctx) { const { source, args } = ctx; return { operation: "Invoke", payload: { field: ctx.info.fieldName, arguments: args, source }, }; } export function response(ctx) { return ctx.result; }