general-config.md

General configuration

Quick start

service: my-app

plugins:
  - serverless-appsync-plugin

provider:
  name: aws

appSync:
  name: my-api

  authentication:
    type: API_KEY

  apiKeys:
    - name: myKey
      expiresAfter: 1M

  dataSources:
    my-table:
      type: AMAZON_DYNAMODB
      description: 'My table'
      config:
        tableName: my-table

  resolvers:
    Query.user:
      dataSource: my-table

Configuration

• name: The name of this AppSync API
• schema: The filename of the schema file. Defaults to schema.graphql. Read more
• authentication: See Authentication
• additionalAuthentications: See Authentication
• apiKeys: See API Keys
• domain: See Custom domains
• dataSources: See DataSources
• resolvers: See Resolvers
• pipelineFunctions: See Pipeline functions
• substitutions: See Substitutions
• caching: See Cacing
• waf: See Web Application Firefall
• logging: See Logging
• xrayEnabled: Boolean. Enable or disable X-Ray tracing.
• visibility: Optional. GLOBAL or PRIVATE. Changing this value requires the replacement of the API.
• tags: A key-value pair for tagging this AppSync API

Schema

There are different ways to define your schema. By default the schema is found in the schema.graphql file. The path of the file is relative to the service directory (where your serverless.yml file is).

appSync:
  name: my-api
  schema: 'mySchema.graphql'

Multiple files

You can specify more than one file as (an array). This is useful if you want to organize your schema into several files.

appSync:
  name: my-api
  schema:
    - 'schemas/user.graphql'
    - 'schemas/posts.graphql'

You can also specify glob expressions to avoid specifying each individual file.

appSync:
  name: my-api
  schema: 'schemas/*.graphql' # include all graphql files in the `schemas` directory

Schema stitching

All the schema files will be merged together before the schema is sent to AppSync. If types are present (extended) in several files, you will need to use Object extension

# base.graphql

# You must create the types before you can extend them.
type Query
type Mutation

# users.graphql

extend type Query {
  getUser(id: ID!): User!
}

extend type Mutation {
  createUser(user: UserInput!): User!
}

type User {
  id: ID!
  name: String!
}

# posts.graphql

extend type Query {
  getPost(id: ID!): Post!
}

extend type Mutation {
  createPost(post: PostInput!): Post!
}

type Post {
  id: ID!
  title: String
  author: User!
}

This will result into the following schema:

type Query {
  getUser(id: ID!): User!
  getPost(id: ID!): Post!
}

type Mutation {
  createUser(user: UserInput!): User!
  createPost(post: PostInput!): Post!
}

type User {
  id: ID!
  name: String!
}

type Post {
  id: ID!
  title: String
  author: User!
}

Limitations and compatibility

AppSync is currently using an older version of the Graphql Specs. This plugin intends to use modern schemas for future-proofing. Incompatibilities will either be dropped or attempted to be fixed.

Descriptions

Descriptions with three double quotes (""") are not supported by AppSync and will be removed.

Old-style descriptions (using #) are supported by AppSync but will be removed by the stitching procedure which does not support them*. Comments are also not supported on enums by AppSync.

* If you want to retain # comments, the workaround is to skip schema stitching by putting your whole schema into one single file.

Multiple interfaces

Types can implement multiple interfaces using an ampersand & in GraphQL, but AppSync uses the old comma (,) separator. & is the only separator supported by this plugin, but it will automatically be replaced with a ,.

Logging

appSync:
  name: my-api
  logging:
    level: ERROR
    retentionInDays: 14

• level: ERROR, NONE, or ALL
• enabled: Boolean, Optional. Defaults to true when logging is present.
• excludeVerboseContent: Boolean, Optional. Exclude or not verbose content (headers, response headers, context, and evaluated mapping templates), regardless of field logging level. Defaults to false.
• retentionInDays: Optional. Number of days to retain the logs. Defaults to provider.logRetentionInDays.
• roleArn: Optional. The role ARN to use for AppSync to write into CloudWatch. If not specified, a new role is created by default.