AWS::Serverless::GraphQLApi
Use the AWS Serverless Application Model (AWS SAM) AWS::Serverless::GraphQLApi
resource type to create
and configure an AWS AppSync GraphQL API for your serverless application.
To learn more about AWS AppSync, see What is AWS AppSync? in the AWS 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
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn’t have an AWS CloudFormation equivalent.
Auth
-
Configure authentication for your GraphQL API.
Type: Auth
Required: Yes
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn’t have an AWS CloudFormation equivalent.
Cache
-
The input of a
CreateApiCache
operation.Type: AWS::AppSync::ApiCache
Required: No
AWS CloudFormation compatibility: This property is passed directly to the AWS::AppSync::ApiCache resource.
DataSources
-
Create data sources for functions in AWS AppSync to connect to. AWS SAM supports Amazon DynamoDB and AWS Lambda data sources.
Type: DataSource
Required: Yes
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn’t have an AWS CloudFormation equivalent.
DomainName
-
Custom domain name for your GraphQL API.
Type: AWS::AppSync::DomainName
Required: No
AWS CloudFormation compatibility: This property is passed directly to the AWS::AppSync::DomainName resource. AWS SAM automatically generates the AWS::AppSync::DomainNameApiAssociation resource.
Functions
-
Configure functions in GraphQL APIs to perform certain operations.
Type: Function
Required: Yes
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn’t have an AWS CloudFormation equivalent.
Logging
-
Configures Amazon CloudWatch logging for your GraphQL API.
If you don’t specify this property, AWS 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
AWS 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
AWS 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
AWS 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. AWS SAM supports JavaScript pipeline resolvers.
Type: Resolver
Required: Yes
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn’t have an AWS CloudFormation equivalent.
SchemaInline
-
The text representation of a GraphQL schema in SDL format.
Type: String
Required: Conditional. You must specify
SchemaInline
orSchemaUri
.AWS 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, AWS CloudFormation requires that the file is first uploaded to Amazon S3 before deployment. You can use the AWS SAM CLI to facilitate this process. For more information, see How to upload local files at deployment with AWS SAM CLI.
Type: String
Required: Conditional. You must specify
SchemaInline
orSchemaUri
.AWS 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
AWS CloudFormation compatibility: This property is passed directly to the
Tag
property of anAWS::AppSync::GraphQLApi
resource. XrayEnabled
-
Indicate whether to use AWS X-Ray tracing for this resource.
Type: Boolean
Required: No
AWS 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; }