generator-cosappsync v0.9.0
Generator: CosAppSync
Prerequesites
It's best to familiarize yourself with these topics if you don't know where to start:
When using dynamodb
as a backend:
When using aurora-postgres
as a backend:
Also worth checking out:
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
4 years ago