To view the repo only containing the code and instructions for deploying these applications, click here.
In this post I’ve created annotated GraphQL schemas that you can use to deploy popular types of applications.
The GraphQL Transform library allows you to deploy AWS AppSync GraphQL APIs with features like NoSQL databases, authentication, elasticsearch engines, lambda function resolvers, relationships, authorization, and more using GraphQL schema directives.
For example, take the following schema that is utilizing the @model
directive:
type Note @model {
id: ID!
name: String!
description: String
}
This schema will deploy the following:
As of this post there are 7 directives offered by the GraphQL Transform library:
@model
// Deploys DynamodDB + resolvers + additional GraphQL schema
@auth
// Allows the definition of auth rules and builds corresponding GraphQL resolvers based on these rules
@connection
// Enables you to specify relationships between `@model` object types
@searchable
// Handles streaming the data of an @model object type to Amazon Elasticsearch Service and configures search resolvers that search that information
@function
// Allows you to quickly & easily configure AWS Lambda resolvers within your AWS AppSync API
@key
// Enables you to configure custom index structures for @model types
@versioned
// Adds object versioning and conflict resolution to a type
Using this library you can deploy the back end for your application using only an annotated GraphQL schema.
In this post I will show example schemas that, when used with the Amplify GraphQL transform library, will build out the backends for many popular types of applications.
For a tutorial showing how to deploy these applications using the GraphQL transform library, check out the documentation here.> Some applications may require additional custom authorization logic for certain subscriptions that you may not want accessible to all users. To learn more, check out the documentation here.## Testing these out
To deploy any of these applications, run the following commands:
Be sure to first install the AWS Amplify CLI
$ amplify init
# if the app needs auth
$ amplify add auth
$ amplify add api
> Choose GraphQL
> If using authentication, choose Amazon Cognito as authentication type
> Update GraphQL schema
# if the app needs storage (i.e. images or video)
$ amplify add storage
$ amplify push
You can now use local mocking to test serverless GraphQL APIs, databases, and serverless functions locally.
$ amplify mock api
Check out this video for a quick overview of local testing:
Let’s start with something very basic: a Todo app.
This app has the following requirements. The user should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type Todo @model {
id: ID!
name: String!
description: String
}
This will deploy the entire GraphQL API including the DynamoDB NoSQL database, additional GraphQL schema for GraphQL CRUD and List operations, GraphQL subscriptions, and the GraphQL resolvers mapping the schema to the database.
Next, let’s look at how we might create an events app. A point to notice here is that we will need to have a way for admins to be able to create, update, and delete events and guests to only be able to read events. We also want to be able to query and get a sorted list (by date) of the events.
Based on these requirements, the user should be able to:
An admin should also be able to:
To build this app, we could use the following annotated GraphQL schema:
type Event
@model
@key(name: "queryName", fields: ["queryName", "time"], queryField: "eventsByDate")
@auth(rules: [{allow: groups, groups: ["Admin"], operations: [create, update, delete]}])
{
id: ID!
name: String!
description: String
time: String!
queryName: String!
}
When creating a new event, we would need to populate the queryName
parameter with a consistent value in order to be able to sort by time of the event:
mutation createEvent {
createEvent(input: {
name: "Rap battle of the ages"
description: "You don't want to miss this!"
time: "2018-07-13T16:00:00Z"
queryName: "Event"
}) {
id name description time
}
}
Note: because
queryName
will be the same (“Event”) value across all items, you could also update the resolver request mapping template to auto-populate this value and therefore not need to specify it in the mutation.
Now, to query for a list of sorted events, you could use the following query:
query listEvents {
eventsByDate(queryName: "Event") {
items {
id
name
description
time
}
}
}
Once you’ve created the authentication by running amplify add auth
, you can run amplify console auth
to add a user to the Admin
group or use a Lambda Trigger to do it automatically when certain users sign up.
This app has the following requirements. The User should be able to:
An admin should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type Customer
@model(subscriptions: null)
@auth(rules: [
{ allow: owner }, { allow: groups, groups: ["Admin"]}
]) {
id: ID!
name: String!
email: String!
address: String
}
type Product @model
@auth(rules: [
{allow: groups, groups: ["Admin"], operations: [create, update, delete]}
]) {
id: ID!
name: String!
description: String
price: Float!
image: S3Object
}
type S3Object {
bucket: String!
region: String!
key: String!
}
type Order @model
@auth(rules: [
{allow: owner}, {allow: groups, groups: ["Admin"]}
]) {
id: ID!
customer: Customer @connection
total: Float!
order: String
}
This app has the following requirements. The User should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type User
@model
@auth(rules: [
{ allow: owner, ownerField: "id", operations: [create, update, delete] }
]) {
id: ID!
username: String!
avatar: S3Object
conversations: [ConvoLink] @connection(name: "UserLinks")
messages: [Message] @connection(name: "UserMessages")
createdAt: String
updatedAt: String
}
type Conversation
@model(subscriptions: null)
@auth(rules: [{ allow: owner, ownerField: "members" }]) {
id: ID!
messages: [Message] @connection(name: "ConvoMsgs", sortField: "createdAt")
associated: [ConvoLink] @connection(name: "AssociatedLinks")
name: String!
members: [String!]!
createdAt: String
updatedAt: String
}
type Message
@model(subscriptions: null, queries: null)
@auth(rules: [{ allow: owner, ownerField: "authorId" }]) {
id: ID!
author: User @connection(name: "UserMessages", keyField: "authorId")
authorId: String
content: String!
image: S3Object
conversation: Conversation! @connection(name: "ConvoMsgs", sortField: "createdAt")
messageConversationId: ID!
createdAt: String
updatedAt: String
}
type ConvoLink
@model(
mutations: { create: "createConvoLink", update: "updateConvoLink" }
queries: null
subscriptions: null
) {
id: ID!
user: User! @connection(name: "UserLinks")
convoLinkUserId: ID
conversation: Conversation! @connection(name: "AssociatedLinks")
convoLinkConversationId: ID!
createdAt: String
updatedAt: String
}
type Subscription {
onCreateConvoLink(convoLinkUserId: ID!): ConvoLink
@aws_subscribe(mutations: ["createConvoLink"])
onCreateMessage(messageConversationId: ID!): Message
@aws_subscribe(mutations: ["createMessage"])
}
type S3Object {
bucket: String!
region: String!
key: String!
}
This app has the following requirements. The User should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type User
@model
@auth(rules: [
{ allow: owner, ownerField: "id", operations: [create, update, delete] }
]) {
id: ID!
username: String!
posts: [Post] @connection
createdAt: String
updatedAt: String
}
type Post @model @auth(rules: [{allow: owner, operations: [create, update, delete]}]) {
id: ID!
postContent: String
postImage: S3Object
comments: [Comment] @connection
votes: Int
}
type Comment @model @auth(rules: [{allow: owner, operations: [create, update, delete]}]) {
id: ID!
text: String!
author: String!
votes: Int
post: Post @connection
}
type Vote @model
@key(name: "byUser", fields: ["createdBy", "createdAt"], queryField: "votesByUser")
{
id: ID!
postId: ID!
createdBy: ID!
createdAt: String!
vote: VoteType
}
type S3Object {
bucket: String!
region: String!
key: String!
}
input VoteInput {
type: VoteType!
id: ID!
}
enum VoteType {
up
down
}
For the voting mechanism to work, we need to make sure that the resolver is incrementing or decrementing the votes
count directly at the DB level. To do that, you will need to create a new mutation and request mapping template to increment and decrement the vote on an item (comment or post).
First, add the following types to your GraphQL schema:
voteForPost(input: ItemVoteInput): Post
input ItemVoteInput {
type: ItemVoteType!
id: ID!
}
enum ItemVoteType {
up
down
}
Then create a custom resolver that would look something like this.
#set($vote = 1)
#if ($context.arguments.input.type == "down")
#set($vote = -1)
#end
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : { "S" : "${context.arguments.input.id}" }
},
"update" : {
"expression" : "ADD votes :votes",
"expressionValues" : {
":votes" : { "N" : $vote }
}
}
}
Now, when creating a vote, you will need to do two things:
You also have the ability to query all votes from a user.
Click here to view AWS AppSync Chat, a completed full-stack version of this app built with React.
This app has the following requirements. The User should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type User
@model
@auth(rules: [
{ allow: owner, ownerField: "id", operations: [create, update, delete] }
]) {
id: ID!
username: String!
conversations: [ConvoLink] @connection(name: "UserLinks")
messages: [Message] @connection(name: "UserMessages")
createdAt: String
updatedAt: String
}
type Conversation
@model(subscriptions: null)
@auth(rules: [{ allow: owner, ownerField: "members" }]) {
id: ID!
messages: [Message] @connection(name: "ConvoMsgs", sortField: "createdAt")
associated: [ConvoLink] @connection(name: "AssociatedLinks")
name: String!
members: [String!]!
createdAt: String
updatedAt: String
}
type Message
@model(subscriptions: null, queries: null)
@auth(rules: [{ allow: owner, ownerField: "authorId" }]) {
id: ID!
author: User @connection(name: "UserMessages", keyField: "authorId")
authorId: String
content: String!
conversation: Conversation! @connection(name: "ConvoMsgs", sortField: "createdAt")
messageConversationId: ID!
createdAt: String
updatedAt: String
}
type ConvoLink
@model(
mutations: { create: "createConvoLink", update: "updateConvoLink" }
queries: null
subscriptions: null
) {
id: ID!
user: User! @connection(name: "UserLinks")
convoLinkUserId: ID
conversation: Conversation! @connection(name: "AssociatedLinks")
convoLinkConversationId: ID!
createdAt: String
updatedAt: String
}
type Subscription {
onCreateConvoLink(convoLinkUserId: ID!): ConvoLink
@aws_subscribe(mutations: ["createConvoLink"])
onCreateMessage(messageConversationId: ID!): Message
@aws_subscribe(mutations: ["createMessage"])
}
This app has the following requirements. The User should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type User
@model
@auth(rules: [
{ allow: owner, ownerField: "id", operations: [create, update, delete] }
]) {
id: ID!
username: String!
posts: [Post] @connection
createdAt: String
updatedAt: String
}
type Post @model @auth(rules: [
{allow: owner, operations: [create, update, delete]}
]) {
id: ID!
postImage: S3Object!
comments: [Comment] @connection
likes: Int
}
type Comment @model @auth(rules: [{allow: owner, operations: [create, update, delete]}]) {
id: ID!
text: String!
author: String!
likes: Int
post: Post @connection
}
type Like @model
@key(name: "byUser", fields: ["createdBy", "createdAt"], queryField: "likesByUser")
{
id: ID!
postId: ID!
createdBy: ID!
createdAt: String!
liked: Boolean
}
type Following @model @key(name: "followerId", fields: ["followerId", "createdAt"], queryField: "listFollowing") {
id: ID
followerId: ID!
followingId: ID!
createdAt: String!
}
type S3Object {
bucket: String!
region: String!
key: String!
}
Similarly to the Reddit clone, we need to have some custom logic in our resolver to handle likes. In the case of Instagram, you probably only want a user to like a post a single time. If they tap like again, you may want to allow them to unlike a post.
We’ll also probably want to keep a total count of likes for a post and for a comment. Luckily, this isn’t that hard to accomplish. With DynamoDB (or any NoSQL database) we can do this directly in a database operation without having to first read from the database.
To implement the like count, we can first create the following GraphQL mutation definition:
likePost(like: Boolean!): Post
#set($like = true)
#if ($context.arguments.like == false")
#set($like = -1)
#end
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : { "S" : "${context.arguments.input.id}" }
},
"update" : {
"expression" : "ADD likes :likes",
"expressionValues" : {
":likes" : { "N" : $like }
}
}
}
Click here to view Conference App in a Box, a completed full-stack version of this app built with React Native.
This app has the following requirements. The User should be able to:
An Admin should be able to:
Based on these requirements we can assume we need the following for this application:
To build this app, we could use the following annotated GraphQL schema:
type Talk @model
@auth(rules: [{allow: groups, groups: ["Admin"], operations: [create, update, delete]}])
{
id: ID!
name: String!
speakerName: String!
speakerBio: String!
time: String
timeStamp: String
date: String
location: String
summary: String!
twitter: String
github: String
speakerAvatar: String
comments: [Comment] @connection(name: "TalkComments")
}
type Comment @model {
id: ID!
talkId: ID
talk: Talk @connection(sortField: "createdAt", name: "TalkComments", keyField: "talkId")
message: String
createdAt: String
createdBy: String
deviceId: ID
}
type Report @model
@auth(rules: [
{allow: owner, operations: [create, update, delete]},
{allow: groups, groups: ["Admin"]}
])
{
id: ID!
commentId: ID!
comment: String!
talkTitle: String!
deviceId: ID
}
type ModelCommentConnection {
items: [Comment]
nextToken: String
}
type Query {
listCommentsByTalkId(talkId: ID!): ModelCommentConnection
}
type Subscription {
onCreateCommentWithId(talkId: ID!): Comment
@aws_subscribe(mutations: ["createComment"])
}
In this schema, notice we are adding an additional subscription to listen to new comments by ID. This way we can only subscribe to comments for the talk that we are currently viewing.
========================================
Thanks for reading :heart: If you liked this post, share it with all of your programming buddies! Follow me on Facebook | Twitter
☞ GraphQL with React: The Complete Developers Guide
☞ The Modern GraphQL Bootcamp (with Node.js and Apollo)
☞ Build a Realtime App with React Hooks and GraphQL
☞ Full-Stack React with GraphQL and Apollo Boost
#graphql #web-development