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 an AWS::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 an AWS::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 an AWS::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 or SchemaUri.

AWS CloudFormation compatibility: This property is passed directly to the Definition property of an AWS::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 or SchemaUri.

AWS CloudFormation compatibility: This property is passed directly to the DefinitionS3Location property of an AWS::AppSync::GraphQLSchema resource.

Tags

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 an AWS::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 an AWS::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;
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

FunctionUrlConfig

ApiKeys