@yippiecloud/cdk-appsync-stack v1.0.31

AppSync Stack using the AWS-CDK

WORK IN PROGRESS

This project tries to implement a simple multi-instance GraphQL based headless CMS based on AWS AppSync and S3 using the AWS CDK. This project follows the GraphQL schema first and a simple JSON file structure approach.

Two GraphQL schema examples (GraphQL Schema Todo and GraphQL Schema Blog) could be installed in AWS AppSync and S3 using the deploy command. For this purpose, two completely independent GraphQL APIs and the corresponding S3 JSON content buckets are generated.

Intention and conceptual background

Reusable application blocks are already commonplace in many areas of software development. (e.g. UI-Libraries, NPM-Modules, etc.) Only with reusable modules/components is it really possible to beeing productive in application development. But at the moment you still need a lot of special cloud know-how to be able to use the Serverless-Cloud architecture effectively in your own project. This project tries to establish a complete and reusable Serverless-Application-Blocks (also called cloud modules) which you can easily integrate, deploy and use in your own application stack using the AWS-CDK.

Architecture and implementation

This project is a reusable AWS-CDK stack implementation that creates a AWS AppSync instance, a AWS S3 bucket and three AWS Lambdas which act as glue in between.

You can use it in your own AWS-CDK-App like this:

#!/usr/bin/env node
import { join } from 'path';
import { App } from '@aws-cdk/core';
import { CdkAppSyncStack } from '@yippiecloud/cdk-appsync-stack';

const app = new App();

// your own stacks ...

new CdkAppSyncStack(app, 'My-Stack-Name', {
  namespace: 'my-name',
  graphQLSchemaFilePath: join(__dirname, `my-schema.graphql`),
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
});

// your own stacks ...

TBD

Setup

yarn

Examples

• GraphQL Schema Todo - a very simple Todo API
• GraphQL Schema Blog - more advanced Blog API with AppSync subscriptions and caching

Deploy the examples using AWS-Vault

aws-vault exec <your-profile-name> --no-session -- yarn deploy

GraphQL schema design conventions

Types

• 1:1 relations can be used e.g. author: Author
• 1:n relations can be used and should end with s e.g. authors: [Author]

Queries

• list queries should end with s e.g. todos: [Todo], posts: [Post]
• entity queries should have a id: ID! argument e.g. todo(id: ID!): Todo

Mutations

• update and insert operation is summarized to one xyzUpsert-Operation
• if the entity with the ID exists it will be completely (atomically) overwritten, if not it will be created
• if no ID is passed, a new entity with a UUID will be created
• names should start with the type name and end with Upsert or Delete e.g. todoUpsert(...), todoDelete(...)
• xyzDelete-Mutation should have id: ID! argument e.g. todoDelete(id: ID!): Todo!
• xyzUpsert-Mutation should have input: TypeInput! argument e.g. todoUpsert(input: TodoInput!): Todo!
• 1:1 or 1:n relations should be designed in input type by using the type name prefix and end with Id e.g. authorId: ID!

Subscriptions

• Keep in mind - AWS AppSync supports only in-process notifications via subscription
• to work wtih subscriptions, add this directive @aws_subscribe(mutations: [String!]!) on FIELD_DEFINITION at the first line of your schema file
• postfix your subscription definition (e.g. authorChanged(id: ID): Author!) using @aws_subscribe(mutations: ["authorUpsert", "authorDelete"])

Open tasks / issues

• publish to NPM
• ignore me resolver
• entity versioning to handle optimistic concurrency in mutations
• auth via Cognito
• cache invalidation (e.g. per user)
• pagination with GraphQL connection pattern
• union type support
• GraphQL search pattern
• export S3 bucket from stack to attach S3 trigger to notify subscribers via SNS, SQS, etc.