The AWS AppSync GraphQL service offers real-time updates and built-in offline support along with first class integration with ElasticSearch, DynamoDB, and AWS Lambda.
AppSync Dashboard
The way that I would describe AppSync is that it is basically a Firebase like service but with more comprehensive database query and search features, as well as a fully managed GraphQL API for your application.
Right now, AppSync has sdks for native iOS, web, and React Native, with Android coming soon.
In this post, I will walk through using AWS AppSync to create a new API endpoint that will provision a DynamoDB table, and walk through the starter project that AppSync provides and discuss how everything is wired together.
We will then look at how you can use AppSync to create new Schemas that will automatically provision additional tables to correlate to the new resources. We will also take a look at how to use resolvers and mapping templates to create custom requests and responses from your GraphQL schemas.
This post will assume you have an AWS account.
Getting Started
The first thing you need to do is log in to the AWS Console and click on AWS AppSync in the Mobile Services section.
Once you are logged into the AppSync console, you will see a screen, which will allow you to go ahead and create a new API (figure 1). If this is your first time here and you have no APIs created, this screen will look different, but will still have the orange Create API button.:
Figure 1: AppSync Console
I will click the orange Create API button and create a new API called EventsApp, and will choose the Event App template which will automatically create a nice basic example schema which we can use to get started, then scroll down and click the orange Create button.
Next, we will be brought to the dashboard for the API we just created. Here, we will see a menu on the left for us not only to explore and edit the schema, but also to test out Queries, add and view existing data sources related to the API, and manage settings (Figure 3).
In this view, we see our API endpoint URL, the auth mode (set to API KEY by default), the API ID and a quick getting started guide for iOS, React Web, and React Native.
We will start by cloning the Web project and plugging in our newly created credentials.
Go ahead and scroll to the bottom of the Getting Started guide and choose Web (React), and copy the cloned repo url (Figure 3).
In a working folder from your command line, let’s go ahead and clone the project:
git clone https://github.com/aws-samples/aws-mobile-appsync-events-starter-react
Next, go ahead and install the dependencies using either npm or yarn:
npm install
or
yarn
Now, we need to add our our AppSync configuration file.
To download the file, click the orange Download button right below where we cloned the repo and download the file into the src folder.
Now, we should be able to go ahead and run the project.
From the root of the directory, run npm start.
npm start
We should see our project running in the browser, and we should now be able to add new events (Figure 4)! Go ahead and add at least one event.
Figure 4: Events App
Now, we should be able to go into our Data Sources and see the new item added to our database.
In the dashboard, click Data Sources and then click on AppSyncEventTable and then click on the items tab (Figure 5).
Figure 5: Viewing the DynamoDB table
Let’s now open up our editor to see how all of this is put together, then we’ll dive deeper into the AWS AppSync dashboard to view the queries and schema powering this application!
In src/App.js, let’s take a look at what is going on:
- We import the downloaded AppSync configuration file. This file contains the
graphqlEndpointwhich is the API URL that was provisioned when the API was created from the AppSync dashboard, theapiKey, as well as a couple of other pieces of configuration. ApolloProviderfrom the Apollo client is imported and used to provide a client instance to a React component tree. This will allow us to attach any React component to our GraphQL endpoint to perform queries and mutations.AWSAppSyncClientis similar to the ApolloClient constructor. It takes a configuration object containing the API url, region, and auth information.Rehydratedis a helper from theaws-appsync-reactlibrary that will basically wait to render the application until the data is fetched from the local cache and the application is wired up with theAWSAppSyncClient- As mentioned in step 3, here we are passing our unique configuration to the
AWSAppSyncClientconstructor. - Here we create the main application component, wrapping the App component in both the
ApolloProvideras well asRehydrated.
Next let’s take a look at src/Components/AllEvents.js and src/GraphQL/QueryAllEvents.js. In these files, you will see a typical GraphQL / Apollo configuration.
The GraphQL query in QueryAllEvents look like this:
import gql from "graphql-tag";
export default gql(`query {listEvents {items {idnamewherewhendescriptioncomments {items {commentId}}}}}`);
This query will fetch an array of event items, each containing an id along with some other information.
Schema
Where exactly is this data coming from? Let’s go back into our AppSync console to see what’s going on! Go to the dashboard for the events app and let’s take a look at the Schema that was generated for us when we created the API (Figure 6).
Figure 6: EventsApp Schema
In this schema, we will see the correlating type called Event along with the listEvents query.
We can also see additional types, queries, and mutations for things like deleting an event, getting a single event by id, among other things.
The next question is probably “How does the database deal with the queries and mutations?”.
The answer is resolvers.
Resolvers
Resolvers offer a way to link database tables (in our case, DynamoDB) to individual queries and mutations.
You can view, attach, and edit resolvers from the Schema view by either clicking on an existing resolver or clicking the Attach button next to an existing data type (Figure 7).
Figure 7: Viewing resolvers
Resolvers use a templating language called Velocity Templating Language (VTL) to map GraphQL queries into a format specific to your data source.
A few of the most most basic queries and mutations that you would need to perform, like getting an item by id or putting in item into an array, are already written for you and available in the dropdown menu when you are creating or editing your resolver (Figure 8).
Figure 8: Mapping Template
Creating a New GraphQL Type + DynamoDB Table
Let’s try walking through the process of creating a new type and query in our schema, and then attaching and testing out a resolver.
In the schema editor, let’s add a new User type then click save (Figure 9).
Figure 9: Adding a User type
After clicking save, click the Create Resources button in the top right corner of the screen above the data types.
In the Create Resources screen, choose User as the type from the dropdown menu, and scroll to the bottom and click the Create button (Figure 10).
Figure 10: Creating a new resource
This do two things:
- Create a new DynamoDB table called
UserTable. - Update the schema, adding queries, mutations, and subscriptions to go along with this new type.
You should be able to now view your data sources and see a new table, automatically created for you, called UserTable. You should also be able to view the new definitions in the schema.
Now, let’s test out the new table and query!
Queries & Mutations
In the left menu of the dashboard, click on Queries. AppSync has an in-browser tool for writing, validating, and testing GraphQL queries!
Create a new mutation query called createUser:
mutation createUser {createUser(input: {name: "Nader Dabit"username: "naderdabit"}) {id}}
Then click the orange play button (Figure 11).
Figure 11: Executing a query
Now, you should be able view the new data in the UserTable!
We can also fetch this data using the getUser query.
Try the following query to fetch the newly created user:
query getUser {getUser(id: "12345") {nameusernameid}}
Security
You can use AWS IAM policies or Cognito User Pools for their directory, as well as custom rules that are set in the GraphQL resolvers to perform runtime checks of authorization rules.
This allows some pretty powerful capabilities like being able to check if a specific user has access to perform an action on a single piece of data — even at the database row level. For example, you can check if a user named Bob was the creator of a record and only allow Bob to be able to read or edit that record. These access checks can be done before the resolver communicates with a data source or after to perform filtering prior to sending data back to the client.
The Cognito User Pools capabilities also allow for “grouping” of users and configuring the resolvers based on these groups. For example, maybe you have Engineering and HR users but only the Engineering users can invoke a specific resolver.
To learn more, check out the docs here.
AWS Amplify
If you’re looking to integrate your client UX with AppSync easily, check out AWS Amplify.
This new library also released last year lets you get things like user Registration and Login easily in your app. It manages the AWS IAM and Cognito User Pools objects (like JWT tokens) so that you can pass them to the AppSync service when you want users to authenticate before running resolvers as outlined in the earlier section.
Amplify works great with AWS resources, for instance it will send Analytics to Amazon Pinpoint and also has a Storage component for uploading & downloading data from S3 which can be locked down on a per-user basis with a “private” setting.
AWS designed it to be open and pluggable for usage with other cloud services that wish to provide an implementation or custom backends which is a nice addition to the Open Source community.
https://www.youtube.com/watch?v=vAjf3lyjf8c&feature=youtu.be&t=3360
Check out this YouTube clip for an overview of Amplify.
To see a general walkthrough of how to create a new AppSync application along with a custom schema, see the following video:
To learn more about AppSync, check out the developer guide as well as the API docs.
Thanks for reading!
I will be doing my best to keep this up to date with the most recent documentation, so feel free to use it as a reference, or to reach out to me at dabit3@gmail.com if you ever have any questions.