Generator: CosAppSync

Prerequesites

It's best to familiarize yourself with these topics if you don't know where to start:

• TypeScript
• GraphQL
• CDK
• AppSync
• Velocity (VTL)

When using dynamodb as a backend:

• DynamoDB

When using aurora-postgres as a backend:

• RDS
• Postgres

Also worth checking out:

• Lambda

How to use

First make sure Yeoman is installed globally: npm install -g yo

Then make Yeoman aware of the generator in this repo:

npm i
npm link

Afterwards you can use the template by running:

yo cosappsync

NOTE: Run this in a different folder, where you want your project to be created in.

Also, the generator will assign a random port to your local endpoint and prints it once it's done.

Structure

The generator supports the following database backends:

- aurora-postgres
- dynamodb

It also generates resolver examples for you:

- Unit Resolver + Go Lambda
- Pipeline Resolver

NOTE: If you choose aurora-postgres you need to have NPM_TOKEN in your env set to a token with access to the Gitlab NPM registry. If you don't know what to do, just poke someone.

Also worth mentioning: The latest supported Postgres version by Aurora is 10.7. Just keep that in mind when developing your schema.

Depending on which you choose, it will setup all necessary files and give you a deployable AppSync project.

The layout of a project is as follows (omitted some files for clarity):

...
lib/ - here is where all the actual logic of the backend is placed
    graphql/ - contains the schema.graphql
    lambdas/ - all lambdas (if any) should go here
    resolvers/ - all resolvers (*.vtl) should go here
    sql/ - contains the schema.sql for providing all tables, functions, triggers, ... only exists when choosing aurora-postgres)
    <project>-stack.ts - the CDK stack containing a GraphQL API, database backend and basic resolvers)
docker/ - contains everything necessary to run the mock API
test/ - some basic boilerplate for writing tests
appsync-mock.json - configuration of the mock API, which is where - amongst others - the connection strings to the databases can be configured as well as the JWT token that is used in the GraphQL editor
...

Working with GraphQL

For working with GraphQL it is a good idea to use the GraphQL editor available at http://localhost:2XXXX (port is randomly chosen when the project is created) which makes writing and testing queries a lot easier thanks to introspection.

API Authentitcation

The API uses OIDC for authorization and therefore you need a valid token. The aforementioned GraphQL editor provides one automatically for you. The used JWT token is defined in the appsync-mock.json.

References

To get more concrete examples, you can use these projects as a reference. Both used this template as a starting point:

Aurora Postgres

https://gitlab.botogames.com/g4g/match3-api

DynamoDB

https://gitlab.botogames.com/g4g/unity-jobs