Ten Tips And Tricks for Improving Your GraphQL API with AWS AppSync (MOB401) - AWS re:Invent 2018

© 2018, Amazon Web Services, Inc. or its affiliates. All rights reserved.
Ten Tips and Tricks for Improving
Your GraphQL API with AWS
AppSync
Michael Paris
SDE
AWS
M O B 4 0 1

Agenda
Schema design
Data design
Using AWS Lambda
Realtime data
Rapid development techniques
Offline data
CI / CD
Operations and monitoring
Testing APIs
Schema governance

Everything in your API revolves around the schema
Here are a few tips to help build more resilient, evolvable schemas
Schema design

Why? GraphQL type names are unique
You may proxy multiple services that expose similarly named data
Tip: Use long, descriptive names that adhere to a pattern
For example, you might use <Service><Type> and have names like AWSLambdaFunction
Use long, descriptive names

Input and output patterns
Use a single input type per mutation field.
type Mutation {
# Use a single input field per mutation
createUserPost(input: CreateUserPostInput!): UserPost
}

Input and output patterns (advanced)
type Mutation {
# Also consider explicit output types
createUserPost(input: CreateUserPostInput!): CreateUserPostOutput
}
# The query reference allows arbitrary reads after a write
type CreateUserPostOutput {
userPost: UserPost
query: Query
}

Input and output patterns (advanced)
mutation ReadAfterWrite {
createUserPost(input: { title: “GraphQL @re:invent” }) {
userPost { title } # Returns the updated object
query { # Perform and arbitrary read after the update in the same req
userFeed {
title
}
}
}
}

Pagination patterns
Come up with a pagination pattern that works for you.
Think about your pagination requirements
Do you need a cursor per item?
What pagination related data do you need access to?
Do the edges in your graph contain data?
For example, is a friendship accepted or not

A simple pagination pattern
# Simple and effective
type UserPostConnection {
items: [UserPost]
nextToken: String
}
type User {
id: ID!
posts: UserPostConnection
}
type UserPost {
id: ID!
content: String
}

A simple pagination pattern
query SimplePaginatedQuery {
listObjects(limit: 10, nextToken: “…”) {
items {
id
title
}
nextToken # Finished when null
}
}

An advanced pagination pattern
# Connections wrap edges.
type UserFriendshipConnection {
edges: [UserFriendshipEdge]
pagination: PageInfo
}
# Edges wrap nodes.
type UserFriendshipEdge {
node: User
cursor: String
isAccepted: Boolean # data on the edge
}
# Wrapper for pagination related data.
type PageInfo {
hasNextPage: Boolean
hasPrevPage: Boolean
count: Int # extra page data
}

An advanced pagination pattern
query AdvancedPaginatedQuery {
listObjects(first: 10, after: “…”) { # or last: 10, before: “…”
edges {
node {
id
title
}
cursor
}
pageInfo { hasNextPage hasPrevPage } # Finished when one is false
}
}

Use the best database for the job
Amazon DynamoDB - A great primary data store that scales
Amazon Elasticsearch Service (Amazon ES) - Rich search over large data sets
Amazon Relational Database Service (Amazon RDS) - Store transactional & relational data
Data design

GraphQL with Amazon DynamoDB
GraphQL Operation DynamoDB Operation
Mutation.create<Type> PutItem
Mutation.update<Type> UpdateItem
Mutation.delete<Type> DeleteItem
Query.get<Type> GetItem
Query.list<Type> Scan or Query
DynamoDB operations map really well to GraphQL

Add relational capabilities to NoSQL
type User {
id: ID!
username: String!
tasks: [Task]
}
type Task {
id: ID!
title: String!
user: User
}
id username
1 Michael
2 Jay
3 Zach
id userId title
1 1 Write Slides
2 1 Prep Demo
3 3 Study For Exam
4 2 Review User Feedback
# Query the Task table’s GSI
# GetItem on the User Table

Add relational capabilities to NoSQL
query GetUserAndOwnedPosts {
getUser(id: “1”) {
id
username
tasks {
id
title
}
}
}
id username
1 Michael
2 Jay
3 Zach
userId id title
1 1 Write Slides
1 2 Prep Demo
3 3 Study For Exam
GetItem
Query a table or index
where userId = $ctx.source.id

And the inverse
query GetUserAndOwnedPosts {
getTask(id: “1”) {
username
owner {
username
}
}
}
id username
1 Michael
2 Jay
3 Zach
id userId title
1 1 Write Slides
2 1 Prep Demo
3 3 Study For Exam

Adding search to an API
Amazon DynamoDB
Low latency & high availability at any scale
Query patterns must be designed into the database structure
Amazon Elasticsearch Service
Rich DSL for full-text search and analytical queries
Often used as a secondary store for ad-hoc queries and analysis

DynamoDB + Amazon ES

Amazon Elasticsearch Service resolvers
query SearchTasks {
searchTasksByTitle(
title: “Demo”
) {
items {
id
title
}
}
}
id userId title
1 1 Write Slides
2 1 Prep Demo
3 3 Study For Exam
GET /tasks/_search
{
"query": {
"match" : {
”title" : ”$ctx.args.title"
}
}
}

Storing files
Amazon Simple Storage Service (Amazon S3)
A low latency, high-availability blob storage service
World-wide CDNs offer improved performance for mobile & web
Use AWS AppSync to store pointers to files in Amazon S3
Use S3 SDKs directly from the client for faster upload & download

Storing files
type User {
id: ID!
username: String!
profilePicture: S3Object
}
type S3Object {
bucket: String
key: String
region: String
}
input S3ObjectInput {
bucket: String!
key: String!
region: String!
}

Saving a file mutation CreateUser {
createUser(input: {
username: “janedoe”,
profilePicture: {
bucket: “unique-bucket-name”,
key: “path/to/file.png”,
region: “us-west-2” }
}) {
id
location { bucket key region }
}
}

Reading files query GetUser {
getUser(id: “1”) {
id
location {
bucket
key
region
}
}
}

Add business logic to an API without deploying servers
Connect any data source, internal or external
Tip: Use a standard event structure when resolving fields with Lambda
Leveraging AWS Lambda

Use a standard event structure
type User {
id: ID!
username: String!
socialFriends: [SocialUser]
}
{
Arguments: $ctx.args,
TypeName: “User”,
FieldName: “socialFriends”,
Source: $ctx.source,
Identity: $ctx.identity
}

Use a standard event structure
type Query {
pingLambda: Boolean
}
{
Arguments: $ctx.args,
TypeName: “Query”,
FieldName: “pingLambda”,
Source: $ctx.source,
Identity: $ctx.identity
}

Should I use a single Lambda function everywhere?
type User {
id: ID!
username: String!
}
type Query {
pingLambda: Boolean
}
const =
=>
=>
const
const
return await

Should I use many Lambda functions?
type User {
id: ID!
username: String!
}
type Query {
pingLambda: Boolean
}
// Implement a specific User.socialFriends function
// Implement a specific Query.pingLambda function

Should I use a single Lambda function everywhere?
Using a single function
Can benefit from container warming
One code base for all of your resolvers can be easier to manage
Using many functions
Greater separation of concerns
Deploy resolvers independently
Split ownership of resolver code to many teams

Real-time data
GraphQL subscriptions enable real-time communication
AWS AppSync doubles as a pub-sub broker via MQTT over WebSockets
Common question:
How to authorize subscriptions?

GraphQL subscriptions
AWS AppSync subscriptions are
reactions to mutations.
Subscribe to any mutation without
additional configuration.
type Mutation {
publish: Message
}
type Subscription {
subscribe: Message
@aws_subscribe(mutations: [“publish”])
}

Authorizing subscriptions
Naïve subscription implementations are subject to fan-out problems
If there are 1M connected clients, how do I authorize & route messages to each client?
1M connected clients * 1M messages = 1 trillion publishes
Two-part solution:
Authorize subscriptions at connect time.
Have the topic names themselves transparently encode comparisons.

type Subscription {
onCreateMessage(chatRoomId: ID!): Message
@aws_subscribe(mutations: [“createMessage”])
}

Subscription queries open connections
subscription AuthorizedSubscription {
onCreateMessage(chatRoomId: “1”) {
id
chatRoomId
content
}
}
chatRoomId

Subscription queries open connections
…
}
}
…
}
}

Mutations publish to topics
mutation CreateMessage {
createMessage(input: {…}) {
id
chatRoomId
content
}
}

Subscriptions are no longer subject to fan-out problems
Publishes are no longer dependent on the # of connected clients.
32 (max) topics * 1M messages = 32M (max) publishes.
This is now a manageable problem.
The solution (recap):
Authorize subscriptions at connect time.
Have the topic names themselves transparently encode any comparisons.

Rapid development techniques
AWS Amplify CLI generates infrastructure via AWS CloudFormation
Leverage the GraphQL transform to quickly build out data models
Use the AWS Amplify framework and codegen to build client apps

AWS Amplify CLI
$ amplify add auth
$ amplify add storage
$ amplify add api
$ amplify push
Add an Amazon Cognito User Pool
Create and secure an Amazon S3 bucket
Add an AWS AppSync API
Deploy via AWS CloudFormation

Rapidly build scalable, data-driven applications
Leverages a new open-source project called the GraphQL Transform
Declaratively define your application’s data model using GraphQL SDL
Check your schema.graphql into git for easy version control
Transforms your data model into a CloudFormation document that implements it
Powered by GraphQL directives
Comes with a set of pre-built transformers
@model, @auth, @connection, @versioned, and @searchable
AWS Amplify + AWS AppSync

The @model transformer
# schema.graphql
type Post @model {
id: ID!
title: String!
}
$ amplify add api

And voila!
AWS
Customer Account
Post Table
type Mutation {
createPost(...): Post
updatePost(...): Post
deletePost(...): Post
}
type Query {
getPost(...): Post
listPosts(...): Post
}
type Subscription {
onCreatePost(...): Post
onUpdatePost(...): Post
onDeletePost(...): Post
}
type Post {
id: ID!
title: String
createdAt: String
updatedAt: String
}
Schema Resolvers DataSources
AWS AppSync
createPost
updatePost
deletePost
getPost
listPosts
Mutation
Query
Post Table
DataSource
Post Table
ARN
IAM Role
ARN

@auth
type Post @model @auth(rules: [
{ allow: owner }
]) {
id: ID!
title: String!
owner: String
}
AWS Cloud
Amazon
DynamoDB
Post Table
type Mutation {
}
type Query {
getPost(...): Post
}
type Subscription {
}
AWS AppSync
createPost
updatePost
deletePost
getPost
listPosts
Mutation
Query
Post Table
DataSource
Post
Table
ARN
IAM Role

@connection
type Post @model {
id: ID!
title: String!
comments: [Comment!]!
@connection(name: “PostComments”)
}
type Comment @model {
id: ID!
content: String!
post: Post
@connection(name: “PostComments”)
}
AWS Cloud
Amazon
DynamoDB
Post Table
type Mutation {
createComment(...): Comment
updateComment(...): Comment
deleteComment(...): Comment
}
type Query {
getPost(...): Post
getComment(...): Comment
listComment(...): Comment
}
type Subscription {
onCreateComment(...): Comment
onUpdateComment(...): Comment
onDeleteComment(...): Comment
}
AWS AppSync
Mutation
Query
Post
DataSource
Post
Table
ARN
IAM Role
Comment
Table
Comment
DataSource
Post
Table
ARN
IAM Role
createComment
updateComment
deleteComment
deletePost
updatePost
createPost
getPost
listPosts
getComment
listComments
Post
comments
Comment
post
gsi-PostComments

Querying with @connection
query GetPostAndComments {
getPost(id: ”1”) {
id
title
comments(limit: 10, nextToken: “...”) {
items {
id
content
}
nextToken
}
}
}
gsi-PostComments

AWS Amplify codegen
$ amplify add codegen
$ amplify codegen
# Generate queries & native types from your GraphQL API
# for iOS, Android, TypeScript, and Flow

Offline and delta sync
Hydrate offline cache from main entity table
Only synchronize the “delta” when coming back online
Reconnection, exponential backoff, and retries handled by client
Base query, subscription, and delta query work together

ID Name Title … timestamp expdate
1 Nadia Hello World 1541884315162 1541884320
2 Pancho I’m Sleepy 1541884359527 1541884364
3 Shaggy Running in the
park
1541884404015 1541884409
ID Name Title …
1 Nadia Hello World
2 Pancho I’m Sleepy
3 Shaggy Running in
the park
CreatePost1 (x) CreateDelta1 (x)
Pipeline resolver
createPost(input: CreatePostInput!): Post
GraphQL schema
mutation add{
createPost(Name:”Nadia” Title:“Hello World” ){
id
Name
Title
}
}
Delta TablePost Table

2 Pancho I’m Sleepy 1541884359527 1541884364
park
1541884404015 1541884409
ID Name Title …
1 Nadia Hello World
park
Unit resolver
(Scan/Query, optional paginate, etc.)
listPosts : [Post]
GraphQL schema
Query list{
listPosts{
items {
id
Name
Title
}
}
}
listDeltas(lastSync: AWSTimestamp!) : [DeltaPost]

2 Pancho I’m Sleepy 1541884359527 1541884364
park
1541884404015 1541884409
ID Name Title …
1 Nadia Hello World
park
Unit resolver
Conditional Scan/Query:
lastSync <= timestamp AND expdate > NOW
listPosts : [Post]
GraphQL schema
Query list{
listDeltas(lastSync:1541884330){
items {
id
Name
Title
}
}
}
listDeltas(lastSync: AWSTimestamp!) : [DeltaPost]

CI/CD with AWS Amplify Console
Simplified workflow for serverless web app development/deployment
Manage multiple environments based on feature branches in git
Atomic deployments via Lambda @ edge
Connect to GitHub, Bitbucket, GitLab, and AWS CodeCommit
Simple web hosting with custom domains

Operations and monitoring
Enable Amazon CloudWatch logs in your AWS AppSync API
APIs come with CloudWatch metrics out of the box
Set alarms on 4xx, 5xx, and latency
Use the AWS Amplify Analytics category for powerful client monitoring

Resolver auditing
Pipeline resolvers allow a resolver to interact with multiple data sources
A pipeline resolver is made up of many “functions” (not the same as Lambda functions)
Create an “Audit” function that reports information about a resolver
Attach this function to all the resolvers you want to audit
Create custom alerts, reports, metrics

Testing APIs
Integration Tests
Trigger integration tests after AWS Amplify console deployments
Run tests in AWS Lambda and trigger using CloudWatch events
Canaries
Try out CloudWatch scheduled events + AWS Lambda
Generate test suites and fuzz APIs
Introspect your APIs schema to generate test suites automatically

Schema governance
Centralized schema governance
Have one team manage the schema for the whole organization
Easier than decentralized governance but puts one team on the spot
Decentralized schema governance
AWS AppSync APIs currently require a single schema document
Build client tools to combine schemas from multiple teams into a single document
GraphQL type extensions allow teams to manage their own sub graph

Thank you!
Michael Paris
parismic@amazon.com
@mikeparisstuff

Ten Tips And Tricks for Improving Your GraphQL API with AWS AppSync (MOB401) - AWS re:Invent 2018

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Ten Tips And Tricks for Improving Your GraphQL API with AWS AppSync (MOB401) - AWS re:Invent 2018

Similar to Ten Tips And Tricks for Improving Your GraphQL API with AWS AppSync (MOB401) - AWS re:Invent 2018 (20)

More from Amazon Web Services

More from Amazon Web Services (20)

Ten Tips And Tricks for Improving Your GraphQL API with AWS AppSync (MOB401) - AWS re:Invent 2018