RFC: AppSync abstraction for SAM

[ssenchenko]

Summary

This RFC seeks feedback on a proposal for a new AWS::Serverless:GraphQLApi resource abstraction for SAM. In this proposal, we outline the challenges SAM customers have authoring AppSync based applications today as well as how a new proposed SAM resource type, AWS::Serverless::GraphQLApi , will simplify the authoring, packaging, and delivery of SAM applications that leverage AppSync.

Problem

AppSync, an AWS service for serverless GraphQL solution, is a popular solution for SAM customers to build backend services for web, mobile, and many other types of applications. However, SAM customers have a few challenges when composing their application’s resources in a SAM template.

1. Currently, SAM customers wanting to use AppSync must use AppSync’s CloudFormation resources in their SAM template, requiring an up-front learning curve.
2. IAM permissions must be managed individually by the user, requiring an IAM expertise to successfully integrate the AppSync data sources with other services like Lambda or DynamoDB.

Ideally, SAM will help reduce the number of CloudFormation resources that must be authored and integrated, the IAM policies needed for resolvers to interact with data sources, and help update AppSync schema and resolver code.

The example below demonstrates the challenge of authoring multiple AppSync resources, a database, and IAM policies to so everything can interact appropriately.

Transform: AWS::Serverless-2016-10-31

Resources:
# ============== Non AppSync resources ==============
  NotesTable:
    Type: "AWS::Serverless::SimpleTable"

# ================= AppSync Access to DynamoDB Table =================
  AppSyncDynamoDBRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Action:
              - sts:AssumeRole
            Principal:
              Service:
                - appsync.amazonaws.com

  AppSyncDynamoDBPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      Roles:
        - !Ref AppSyncDynamoDBRole
      PolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Action:
              - dynamodb:GetItem
              - dynamodb:PutItem
              - dynamodb:DeleteItem
              - dynamodb:UpdateItem
              - dynamodb:Query
              - dynamodb:Scan
              - dynamodb:BatchGetItem
              - dynamodb:BatchWriteItem
            Resource: !Join [ "", [ !GetAtt NotesTable.Arn, "*" ] ]

# ================= AppSync Resources =================
  AppSyncApi:
    Type: "AWS::AppSync::GraphQLApi"
    Description: "The GraphQL API for the Notes App"
    Properties:
      AuthenticationType: API_KEY
      Name: Api

  AppSyncSchema:
    Type: "AWS::AppSync::GraphQLSchema"
    Properties:
      ApiId: !GetAtt AppSyncApi.ApiId
      Definition: |
        type Note {
          id: ID!
          title: String
          content: String
        }
        type Query {
          getNote(id: ID!): Note
        }
        type Mutation {
          saveNote(id: ID!, title: String!, content: String!): Note!
          deleteNote(id: ID!): Note
        }
        schema {
          query: Query
          mutation: Mutation
        }

  ApiKey:
    Type: AWS::AppSync::ApiKey
    Properties:
     ApiId: !GetAtt AppSyncApi.ApiId
     ExpiresOn: 1697526000000

  NotesTableDataSource:
    Type: "AWS::AppSync::DataSource"
    Properties:
      ApiId: !GetAtt AppSyncApi.ApiId
      Name: NotesTableDataSource
      Type: AMAZON_DYNAMODB
      ServiceRoleArn: !GetAtt DynamoDBRole.Arn
      DynamoDBConfig:
        TableName: !Ref NotesTable
        AwsRegion: !Sub ${AWS::Region}

  GetNoteResolver:
    Type: "AWS::AppSync::Resolver"
    DependsOn: AppSyncSchema
    Properties:
      ApiId: !GetAtt AppSyncApi.ApiId
      DataSourceName: !GetAtt NotesTableDataSource.Name
      TypeName: Query
      FieldName: getNote
      RequestMappingTemplate: |
        {
          "version": "2017-02-28",
          "operation": "GetItem",
          "key": {
            "NoteId": $util.dynamodb.toDynamoDBJson($context.arguments.NoteId)
          }
        }
      ResponseMappingTemplate: "$util.toJson($context.result)"

  SaveNoteResolver:
    Type: "AWS::AppSync::Resolver"
    DependsOn: AppSyncSchema
    Properties:
      ApiId: !GetAtt AppSyncApi.ApiId
      TypeName: Mutation
      FieldName: saveNote
      DataSourceName: !GetAtt NotesTableDataSource.Name
      RequestMappingTemplate: |
        {
          "version": "2017-02-28",
          "operation": "PutItem",
          "key": {
            "NoteId": $util.dynamodb.toDynamoDBJson($context.arguments.NoteId)
          },
          "attributeValues": {
            "title": $util.dynamodb.toDynamoDBJson($context.arguments.title),
            "content": $util.dynamodb.toDynamoDBJson($context.arguments.content)
          }
        }
      ResponseMappingTemplate: "$util.toJson($context.result)"

  DeleteNoteResolver:
    Type: "AWS::AppSync::Resolver"
    DependsOn: AppSyncSchema
    Properties:
      ApiId: !GetAtt AppSyncApi.ApiId
      TypeName: Mutation
      FieldName: deleteNote
      DataSourceName: !GetAtt NotesTableDataSource.Name
      RequestMappingTemplate: |
        {
          "version": "2017-02-28",
          "operation": "DeleteItem",
          "key": {
            "NoteId": $util.dynamodb.toDynamoDBJson($context.args.NoteId)
          }
        }
      ResponseMappingTemplate: "$util.toJson($context.result)"

Proposed Solution

Overview

Serverless Application Model (SAM) Transform has been successfully providing higher level abstractions for CFN serverless resources. At the same time, SAM CLI delivers developer tools for code deploy, debugging and testing. SAM philosophy is to concentrate on the most frequent use cases and set properties’ defaults to improve UX for those frequent cases first of all. Following this spirit, SAM abstraction for GraphQL will address following aspects

• uploading schema and resolver code with SAM CLI, like it’s done for Serverless::Function
• common, api level, settings for paths to project code
• native support for DynamoDB and Lambda data sources, including IAM policy generation to access them
• close integration between Lambda data source and resolvers and functions
• native support for Javascript Unit and Pipeline resolvers and functions

The above CFN example will look like following with SAM GraphQLApi resource, considering that all VTL resolvers are rewritten in JS and project has the following structure:

.
├── functions
│   ├── deleteNote.js
│   ├── getNote.js
│   └── saveNote.js
├── schema.graphql
└── template.yaml

Transform: AWS::Serverless-2016-10-31

Resources:
  NotesTable:
    Type: "AWS::Serverless::SimpleTable"

  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      Name: MyNotes
      SchemaUri: "schema.graphql"
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: "1.0.0"
      Auth:
        Type: API_KEY
      ApiKeys:
        OneKeyToRuleThemAll:
          ExpiresOn: 2023-10-17
      DataSources:
        DynamoDB:
          NotesTable:
            TableName: !Ref NotesTable
      Resolvers:
        Mutation:
          saveNote:
            Pipeline: 
              - saveNote
          deleteNote:
            Pipeline: 
              - deleteNote
        Query:
          getNote:
            Pipeline: 
              - getNote
      PipelineFunctions:
        getNote:
          DataSource: NotesTable
          CodeUri: "function/getNote.js"
        deleteNote:
          DataSource: NotesTable
          CodeUri: "functions/deleteNote.js"
        saveNote:
          DataSource: NotesTable
          CodeUri: "functions/saveNote.js"

Though each part of SAM GraphQLApi is described below, here are some notes on major differences between SAM and AppSync resources:

• SAM CLI allows to use local paths and deploy code changes easily
• Role and policy to access DynamoDB table is generated by SAM
• Resolvers are grouped by their types like in Schema
• SAM generates code to redirect request/response to/from functions for Pipeline resolvers

Properties and resources which are mapped 1:1 with AppSync

Some properties exactly match those of AppSync resources

• Name (of API)
• Tags
• XrayEnabled
• AuthenticationType (Auth.Type in SAM)
• LambdaAuthorizerConfig (Auth.Config in SAM; additionally, SAM will generate policy to call Lambda Authorizer function)
• OpenIDConnectConfig
• AdditionalAuthenticationProviders
• Schema InlineCode or CodeUri (to Definition and DefinitionS3Location of AWS::AppSync::GraphQLSchema )
• Cache (to AWS::AppSync::ApiCache)

Logging is enabled by default and SAM creates LogGroups if none are provided.
DomainName has all fields of AWS::AppSync::DomainName and AWS::AppSync::DomainNameAssociation is generate by SAM.
ApiKeys maps to AWS::AppSync::ApiKey and will support ExpiresOn as a date (as opposed to AppSync resource which supports only double)

  ApiKeys:
    - OneKeyToRuleThemAll:
        ExpiresOn: 2023-10-17
    - OnlyToRead: {}

Data Sources

There are 2 natively supported data sources: DynamoDb and Lambda. DataSources are grouped by their type so the structure is flattened and all properties from Config are moved one level up to the data source itself.

For DynamoDb the only required property is TableName. DataSource Name property becomes optional and set Logical ID by default. AwsRegion is also optional and populated by default with AWS::Region (stack region).
Role and Policy to access DynamoDb Table is generated by SAM in the same manner as it’s done by Connectors. Default access level will be Read and Write, but it’s possible to choose only one of them.

  DataSources:
    DynamoDB:
      NotesReadWriteDataSource:
        TableName: !Ref NotesTable
      NotesReadDataSource:
        TableName: !Ref NotesTable 
        Permissions:
          - Read
    Lambda:
      NotifierDataSource:
        LambdaArn: !GetAtt NotifierLambda.Arn

Lambda data source can be also defined in a similar manner which is useful when it should be referenced in an AppSync data source, outside of SAM GraphQLApi resource. See more on that in FAQ.

There is no need to manually create DataSource of type NONE, SAM generates it. More on that in AppSync Resolvers and Functions sections below.

Lambda Resolvers

In addition to having 2 separate resources like AppSync, SAM offers a shortcut to merge Lambda data source and resolver which works with Lambda data source into a single abstraction. The reason for that is that Lambda data source acts as a resolver and allows to remove runtime restrictions which exist for AppSync resolvers.

Permissions to AppSync data source to invoke Lambda functions will be generated by SAM.
Since JS unit resolvers are not supported currently, SAM generates a resolver and a function to perform request/response redirection to/from Lambda.

      Resolvers:
        Query: # type name
          allMyNotes: # field name
            LambdaArn: !GetAtt AllMyNotes.Arn

Pipeline Resolvers and Functions

With introducing JS pipeline resolvers AppSync solved 2 problems which existed before:

1. VTL is hard
2. resolvers might require to operate on data from more than 1 data source.

SAM GraphQLApi supports only JS and pipeline resolvers as they are the most convenient and full solution exiting. Only Pipeline resolvers are available at the moment. JS unit resolvers will be supported as soon as AppSync adds them.

SAM resolvers are grouped by field type Query, Mutation, Subscription, or any type name the same way, fields are grouped in the GraphQL schema file.

Resolvers:
  Mutation: # field type
    saveNote: # field name
      Pipeline: 
        - saveNote
        - sendNotification # defined in separate Functions sections
  Note: # type Note from Schema
    content: # content field from Note 
      Pipeline: 
        - getContent
  Query:
    getNote:
      Pipeline: 
        - getNote
        - sendNotification # defined in separate Functions sections
PipelineFunctions:
  saveNote:
    DataSource: NotesReadWrite
    CodeUri: "functions/saveNote.js"
  getContent:
    DataSource: NotesReadWriteDataSource
    CodeUri: "functions/getContent.js"
  getNote:
    DataSource: NotesReadWriteDataSource
    CodeUri: "functions/getNote.js"
  sendNotification:
    DataSource: None
    CodeUri: "functions/saveNote.js"

SAM generates inline code to stash all resolver incoming parameters so they are available in the first function and to redirect response from the last function in the pipeline. To override that code, define CodeUri with a path to the file with the resolver code or use InlineCode field.

DataSource with type NONE is generated by SAM if a function or a resolver has DataSource: None.

FAQ

Why SAM GraphQLApi doesn’t have native support for VTL resolvers? AppSync recommends to use JS resolvers and pipeline functions. VTL is supported by AppSync for backward compatibility.

I prefer or need to use VTL. Can I do it with SAM GraphQLApi? Yes. It’s still possible to use AppSync VTL resolvers with SAM GraphQLApi. AppSync resources should be defined separately but they can reference SAM ApiId or DataSourceName from SAM resource. Here is an example:

Transform: AWS::Serverless-2016-10-31

Resources:
  NotesTable:
    Type: "AWS::Serverless::SimpleTable"

  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      Name: MyNotes
      SchemaUri: "schema.graphql"
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: "1.0.0"
      Auth:
        Type: API_KEY
      ApiKeys:
        OneKeyToRuleThemAll:
          ExpiresOn: 2023-10-17
      DataSources:
        DynamoDB:
          NotesTable:
            TableName: !Ref NotesTable

  GetNoteResolver:
    Type: "AWS::AppSync::Resolver"
    Properties:
      ApiId: !GetAtt SamGraphQl.ApiId
      # using CFN resource Logical ID, the way it's done now in other resources like Serverless::HttpApi
      DataSourceName: !GetAtt SamGraphQlDataSourceNotesTable.Name
      TypeName: Query
      FieldName: getNote
      RequestMappingTemplate: |
        {
          "version": "2017-02-28",
          "operation": "GetItem",
          "key": {
            "NoteId": $util.dynamodb.toDynamoDBJson($context.arguments.NoteId)
          }
        }
      ResponseMappingTemplate: "$util.toJson($context.result)"

Can I use SAM GraphQLApi if I’m working with a data source which is not supported by SAM (ie Relation DB, HttpApi etc)? Yes. An AppSync data source can be define outside of SAM GraphQLApi and then referenced in a resolver or a pipeline function using DataSourceName property (contrary to DataSource property which is used for a data source defined inside SAM resource).

Transform: AWS::Serverless-2016-10-31

Resources:
  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      Name: MyNotes
      SchemaUri: "schema-v1.graphql"
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: "1.0.0"
      Auth:
        Type: API_KEY
      ApiKeys:
        OneKeyToRuleThemAll:
          ExpiresOn: 2023-10-17
      Resolvers:
        Mutation:
          makeCoffe:
            Pipeline: 
              - makeCoffee
      PipelineFunctions:
        makeCoffe:
            DataSourceName: !GetAtt HttpApiDataSource.Name
            CodeUri: "functions/makeCoffee.js"

  HttpApiDataSource:
    Type: "AWS::AppSync::DataSource"
    Properties:
      ApiId: !GetAtt SamGraphQl.ApiId
      Name: CoffeeMaker
      Type: HTTP
      HttpConfig:
        Endpoint: "https://remote-coffee.machine/"

Is it necessary to move all pipeline functions inside SAM GraphQLApi resource to use them in pipeline resolvers defined inside SAM resource? No. It’s possible to use AppSync FunctionConfiguration resource. It must be referenced by FunctionId like in an AppSync resolver.

Transform: AWS::Serverless-2016-10-31

Resources:
  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      Name: MyNotes
      SchemaUri: "schema-v1.graphql"
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: "1.0.0"
      Auth:
        Type: API_KEY
      ApiKeys:
        OneKeyToRuleThemAll:
          ExpiresOn: 2023-10-17
      Resolvers:
        Mutation:
          playMusic:
            Pipeline: 
              - playMusic
      PipelineFunctions:
        playMusic:
            Id: !GetAttr AppSyncPlayMusicFunction.FunctionId

  AppSyncPlayMusicFunction:
    Type: AWS::AppSync::FunctionConfiguration
    Properties: 
      ApiId: !GetAtt SamGraphQl.ApiId
      CodeS3Location: "s3://my-library/utilitites/playMusic.js"
      DataSourceName: !GetAtt HttpApiDataSource.Name
      Name: PlayMusic
      Runtime: 
        Name: APPSYNC_JS
        RuntimeVersion: "1.0.0"
        
  HttpApiDataSource:
    Type: "AWS::AppSync::DataSource"
    Properties:
      ApiId: !GetAtt SamGraphQl.ApiId
      Name: MyPlayer
      Type: HTTP
      HttpConfig:
        Endpoint: "https://amazon.music/"

[aleguern]

That's a great idea, the template in its actual form is very verbose ...

[ccaum]

Thank you for your feedback! Would you like to see us reduce the number of required properties and implement more sensible out-of-the-box defaults? Do you have any thoughts on what you think can be replaced with defaults and what those defaults should be?

[aleguern]

My typical mutation could look like this :

 JoinListFunction:
    Type: AWS::AppSync::FunctionConfiguration
    Properties:
      Name: joinListUser
      FunctionVersion: 2018-05-29
      DataSourceName: !GetAtt UsersDataSource.Name
      ApiId: !GetAtt GraphQLApi.ApiId
      CodeS3Location: "infra/dist/joinList.js"
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: 1.0.0
  JoinList:
    Type: AWS::AppSync::Resolver
    Properties:
      ApiId: !GetAtt GraphQLApi.ApiId
      FieldName: joinList
      TypeName: Mutation
      Runtime:
        Name: APPSYNC_JS
        RuntimeVersion: 1.0.0
      CodeS3Location: "infra/dist/pipeline.js"
      Kind: PIPELINE
      PipelineConfig:
        Functions:
          - !GetAtt JoinListFunction.FunctionId

I have to repeat multiple time this chunk of code, maybe it should be default and overridable ?

Runtime:
        RuntimeVersion: 1.0.0
        Name: APPSYNC_JS

What would really help is that I often find myself using pipeline even though I only call one datasource, I would love to go back to the way I used to with VTL and have a JS unit resolver. (maybe out of this RFC scope)

[ssenchenko]

We have good news, new resource will address both issues you mentioned.

1. Set runtime on the resource level

  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      SchemaUri: "./schema-v1.graphql"
      CodeSettings:
        Runtime:
          Name: APPSYNC_JS
          RuntimeVersion: "1.0.0"
      ...

2. SAM will support JS unit resolvers as soon as AppSync supports them. Meanwhile, we're offering inline function definitions for pipeline resolvers. Your example will look like

  SamGraphQl:
    Type: "AWS::Serverless::GraphQLApi"
    Properties:
      ...
      CodeSettings:
        Runtime:
          Name: APPSYNC_JS
          RuntimeVersion: "1.0.0"
    DynamoDBDatasources:
      UsersDataSource:
        ...
    AppSyncResolvers:
      Mutation:
        joinList:
          DataSource: UsersDataSource # or define it in the Function
          Functions:
            joinListUser:
              CodeUri: "infra/dist/joinList.js"
              # DataSource: UsersDataSource # also possible

[buggy]

I'm glad to see the SAM team are looking into providing a simplified syntax for AppSync. I have a number of concerns with the proposal that broadly fall into scalability (large API's) and consistency (does this feel like the rest of SAM or are we doing something different):

Scalability

1. How would you split an API across multiple CloudFormation templates?

   It's my understanding that the SAM transformation turns the AWS::Serverless::GraphQLAPI resource type into the underlying AWS::AppSync::* and other resources types for CloudFormation to deploy. AppSync API's are commonly split across multiple templates because even a moderately complex API can require hundreds of CloudFormation resources. If everything is sitting under one AWS::Serverless::GraphQLAPI resource and the transformed CloudFormation exceeds the 500 resources limit then what does the developer do? Are they forced to rebuild the CloudFormation stack using the underlying resource types?

   Personally I would like to see an approach which combines the AWS::AppSync::GraphQLApi, AWS::AppSync::GraphQLSchema, AWS::AppSync::ApiKey, AWS::AppSync::ApiCache, AWS::AppSync::DomainName and AWS::AppSync::DomainNameApiAssociation into a single AWS::Serverless::GraphQLApi without the data sources, functions and resolvers. This would allow them to be split across multiple templates referencing the AWS::Serverless::GraphQLApi resource.

Consistency

2. The AWS::Serverless::Function resource type consistently uses the Event property to configure events that trigger the Lambda except for this new AppSync resource type. Is there a reason for that? It seems to be creating an unnecessary inconsistency.

   An AppSync event type could be added to AWS::Serverless::Function with an ApiId property, either TypeName and FieldName (resolver) or FunctionName (function) , and MaxBatchSize (optional). From that it should be possible to create an AWS_LAMBDA integration. Additional optional fields may also be desirable but I would only add those as requested.

3. It's likely that AWS::Serverless::GraphQLFunction and AWS::Serverless::GraphQLResolver resources types would need to be added too. These could be based on the existing AWS::AppSync::FunctionConfiguration and AWS::AppSync::Resolver resource types so they're familiar. Defaults can be set using the SAM Globals section like they are for AWS::Serverless::Function rather than defining a new CodeSettings property that works like Globals.

Globals:
  GraphQLFunction:
    CodeS3Location: path/to/{Name}.{RuntimeFileExtension}
    Runtime:
      Name: APPSYNC_JS
      RuntimeVersion: 1.0.0
  GraphQLResolver:
    RequestMappingTemplateS3Location: path/to/{TypeName}.{FieldName}.request.{RuntimeFileExtension}
    ResponseMappingTemplateS3Location: path/to/{TypeName}.{FieldName}.response.{RuntimeFileExtension}
    Runtime:
      Name: APPSYNC_JS
      RuntimeVersion: 1.0.0

4. SAM recently introduced connectors as an abstract resource type to "provides simple and well-scoped permissions between your serverless application resources". If this is the SAM recommended approach then shouldn't these effectively replace data sources?

   I would propose supporting connectors between the AWS::Serverless::GraphQLFunction and AWS::Serverless::GraphQLResolver resources types proposed in point 3 and every resource that can be a datasource (DynamDB table, Elasticsearch, EventBridge, Lambda, OpenSearchService, etc). This would create the relevant AWS::AppSync::DataSource and the permissions required.

   That would cover everything except the HTTP connector for which a few extra properties could be added to the GraphQLFunction and GraphQLResolver resource types.

5. SAM and the AWS CLI seem to support the same packaging of local files. It would be a shame to have that diverge suddenly. You can see what I mean on this page https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html

You'll notice that only one of my points is to make sure that we can build large API's. The rest are an attempt to make the new Serverless AppSync resources feel like SAM instead of something that's just been bolted on.

[ssenchenko]

Thank you a lot for taking your time and giving a very detailed feedback!

1. Our understanding is that the reason why GraphQL templates tend to spread over several templates is the necessity to use inline code, which contributes to templates becoming too large. And with SAM CLI support to upload and update files in an S3 bucket, the size of templates will reduce.

   However, if it’s necessary, it’ll be still possible to add data sources and resolvers to Aws::Serverless::GraphQLApi in another template. Just to use AppSync::DataSource and AppSync::Resolver and reference ApiId of SAM resource. Would that meet your need?

2. AWS::Serverless::GraphQLApi provides LambdaResolver abstraction, which is a combination of Lambda data source and a unit resolver. Since it’s not a pure Lambda, we’re not sure if it should appear in the Event section of Serverless::Function.

   Another, Lambda function which is used in GraphQLApi is an Api authoriser. We are considering making it available as an Event type later for invoking Lambda functions after launching GraphQLApi resource

3. We will definitely implement passing parameters through Globals, as it’s how it works for other SAM resources. It’ll be either on the resource launch or in a fast flow.

4. AppSync::DataSource doesn’t manage permissions itself. It serves as a proxy object for a data providing service and manages physical connection. We preserve that role of DataSource in GraphQLApi resource. At the same time, SAM connector is an abstraction over permissions and we are not planning to extend its functionality any time soon. Therefore, connectors are not going to replace data sources. But, they can be used together with data sources.

   For 2 data sources natively supported in Aws::Serverless::GraphQLApi: DynamoDB and Lambda - we use connectors under the hood, to generate permissions. To do that, we are adding connectors between AppSync::DataSource and those resources. We might add later connectors for other data sources supported by AppSync.

5. We are going to launch Aws::Serverless::GraphQLApi with SAM CLI package and deploy support. Is there more you’re hoping to see SAM CLI support?

[buggy]

1. Our understanding is that the reason why GraphQL templates tend to spread over several templates is the necessity to use inline code, which contributes to templates becoming too large. And with SAM CLI support to upload and update files in an S3 bucket, the size of templates will reduce.
   However, if it’s necessary, it’ll be still possible to add data sources and resolvers to `Aws::Serverless::GraphQLApi` in another template. Just to use `AppSync::DataSource` and `AppSync::Resolver` and reference ApiId of SAM resource. Would that meet your need?

That won't solve the problem.

File size is just one aspect. If that's the problem you're trying to solve then expand the AWS/SAM CLI packaging support for the RequestMappingTemplateS3Location or ResponseMappingTemplateS3Location properties of AWS::AppSync::FunctionConfiguration resource to include the CodeS3Location property and you're done.

See https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html

AppSync can require a large number of CloudFormation resource. It really depends how complex the schema is, how many resolvers need to be implemented and how many functions you need. With the old 200 resource limit I could almost guarantee anything except the simplest of API would need to be split. It's harder with the 500 resource limit.

You may also want to split the API just to make it easier to work with. One stack to deploys the API + schema. Other stacks act like microservices implementing the resolvers / functions / data source.

2. `AWS::Serverless::GraphQLApi` provides LambdaResolver abstraction, which is a combination of Lambda data source and a unit resolver. Since it’s not a pure Lambda, we’re not sure if it should appear in the `Event` section of `Serverless::Function`.

How is needing to create an AppSync data source any different from what happens with other AWS::Serverless::Function event sources? Isn't the whole point of having an events property on AWS::Serverless::Function that SAM will wire it up correctly without needing to manually create the intermediate objects?

   Another, Lambda function which is used in `GraphQLApi` is an Api authoriser. We are considering making it available as an `Event` type later for invoking Lambda functions after launching `GraphQLApi` resource

This sounds like the complete opposite of what SAM does with AWS::Serverless::Api. Doing that will confuse people who use both.

3. We will definitely implement passing parameters through `Globals`, as it’s how it works for other SAM resources. It’ll be either on the resource launch or in a fast flow.

Thanks.

4. `AppSync::DataSource` doesn’t manage permissions itself. It serves as a proxy object for a data providing service and manages physical connection. We preserve that role of `DataSource` in `GraphQLApi` resource. At the same time, SAM connector is an abstraction over permissions and we are not planning to extend its functionality any time soon. Therefore, connectors are not going to replace data sources. But, they can be used together with data sources.
   For 2 data sources natively supported in `Aws::Serverless::GraphQLApi`: DynamoDB and Lambda - we use connectors under the hood, to generate permissions. To do that, we are adding connectors between `AppSync::DataSource` and those resources. We might add later connectors for other data sources supported by AppSync.

I think I've worded my connector suggestion badly. What I had in mind is something like:

AppSyncToDynamoDB:
  Type: AWS::Serverless::Connector
  Properties:
    Source:
      Id: MyApi
    Destination:
      Id: MyDynamoDBTable
    Permissions:
      - Read
      - Write

Would it be possible to take this and turn it into both the AppSync Data Source and the IAM role use to access it? This really only works if the data sources are external to the proposed Aws::Serverless::GraphQLApi resource.

5. We are going to launch Aws::Serverless::GraphQLApi with SAM CLI package and deploy support. Is there more you’re hoping to see SAM CLI support?

Fix the automatic packaging for CodeS3Location property of AWS::AppSync::FunctionConfiguration resources. If you do that then I can ignore the AWS::Serverless::GraphQLApi and continue using the AWS::AppSync::* resources.

[ssenchenko]

Thank you for your consistent interest in improving SAM GraphQLApi design.

We discussed separating Resolvers and DataSources from the rest of GraphQLApi properties and decided not to follow that path as it increases the complexity of the abstraction and significantly diminishes the number of ways how SAM can simplify AppSync resources and reduce boilerplate. Standalone SAM DataSource and Resolver wouldn't be much different from their AppSync ancestors. Therefore, we offer GraphQLApi as a single resource abstraction which can be referenced in AppSync resources as shown in the FAQ section of RFC. It's possible to create an AppSync Resolver, for example, which references ApiId and DataSourceName from GraphQLApi resource defined in another template.

It's very likely that we'll add GraphQLApi support for Event section of Serverless::Function later. But we are not planning to do it at launch.

Would it be possible to take this and turn it into both the AppSync Data Source and the IAM role use to access it?

This is exactly what I meant by extending functionality of Connector which now generates only a policy but would need to generate a non-permission-related resource as well. We are not planning to extend connectors like that, at this time.
However, it's possible to use same Read and Write access categories, like in a Connector, for DynamoDB data sources defined inside GraphQLApi (with Read + Write access by default):

  DynamoDbDataSources:
    NotesReadWriteDataSource:
      TableName: !Ref NotesTable
    NotesReadDataSource:
      TableName: !Ref NotesTable 
      Permissions:
        - Read

Fix the automatic packaging for CodeS3Location property of AWS::AppSync::FunctionConfiguration resources.

Have you tried to submit a ticket directly at SAM CLI repo? It'd be the fastest way to let the cli team know about the problem.

[buggy]

In case anyone reads this far...

I decided to follow up on the CodeS3Location issue. Point 3 of "the problem" in the RFC is incorrect.

SAM CLI does not currently assist with uploading code files for AppSync resolver functions and schema to S3. SAM customers must rely on inline definitions for schema and resolvers to ensure that code change will be deployed since using S3 paths requires to change path after each code change.

SAM CLI does automatically upload code files for AppSync resolvers, functions and schemas to S3. You can take advantage of this by referencing a local file in the CodeS3Location, RequestMappingTemplateS3Location and ResponseMappingTemplateS3Location properties for resolvers / functions or the DefinitionS3Location property for the schema.

It will also correctly handle when the template hasn't changed but the contents of those files has by uploading a new file to S3 under a different name.

The AWS CLI has similar support except for the CodeS3Location property.

[ssenchenko]

Thank you for pointing to that. I wasn't sure for how long that packaging support exists in SAM CLI but it appears that it's been there already for a couple of years

[buggy]

How would the new Typescript support fit into this?

https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html#additional-utilities

[ssenchenko]

We are considering to add TS support to sam build but we might first launch without it.

[SimonCMoore]

We listened and made building a serverless GraphQL API a bit easier with a new abstraction AWS::Serverless::GraphQLApi. https://aws.amazon.com/about-aws/whats-new/2023/06/aws-appsync-abstraction/

[iamnotadamkr]

@SimonCMoore @ssenchenko Is it available already? We are using aws sam cli 1.89.0 and we are not able to use it. sam validate --lint doesn't recognize new properties (f.e. E3002 Invalid Property Resources/GraphQLApi/Properties/DataSources) and deployment fails for the same reason.

[SimonCMoore]

Yes it is available in SAM service and SAM CLI. Sorry you are having trouble.

I am not able to replicate your error message. I tested using examples @ssenchenko made, please try these and see if you have the same issue? If you do it is probably an issue with the CLI install, if you do not it is probably a template specific issue

1. Example with DDB data source https://github.com/ssenchenko/GraphQL-API-Example/tree/main/examples/updated/e6
2. Another example which uses Lambda DataSource https://github.com/ssenchenko/GraphQL-API-Example/tree/main/examples/updated/e8

If you use Visual Studio code with the AWS Toolkit plugin (and ensure YAML and not ssm-yaml asl-yaml is the type) it will lint and give you hopefully more detailed errors and contextual properties help ( other editors can use the schema as detailed in #2645 )

Note this discussion thread is closed and we may not notice responses, if you are still having issues please open a new issue. Thanks

[iamnotadamkr]

Thank you very much, I went line by line through the examples you gave and noticed that I made a mistake and used AWS::AppSync::GraphQLApi instead of AWS::Serverless::GraphQLApi. Now it works great!

[SimonCMoore]

Yes it is available in SAM service and SAM CLI. Sorry you are having trouble.

I am not able to replicate your error message. I tested using examples @ssenchenko made, please try these and see if you have the same issue? If you do it is probably an issue with the CLI install, if you do not it is probably a template specific issue

1. Example with DDB data source https://github.com/ssenchenko/GraphQL-API-Example/tree/main/examples/updated/e6
2. Another example which uses Lambda DataSource https://github.com/ssenchenko/GraphQL-API-Example/tree/main/examples/updated/e8

If you use Visual Studio code with the AWS Toolkit plugin (and ensure YAML and not ssm-yaml asl-yaml is the type) it will lint and give you hopefully more detailed errors and contextual properties help ( other editors can use the schema as detailed in #2645 )

Note this discussion thread is closed and we may not notice responses, if you are still having issues please open a new issue. Thanks