The GraphQL service offers real-time updates and built-in offline support along with first class integration with ElasticSearch, DynamoDB, and AWS Lambda. AWS AppSync 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 button.: Create API Figure 1: AppSync Console I will click the orange button and create a new API called , 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 button. Create API EventsApp Create 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 guide and choose Web (React), and copy the cloned repo url (Figure 3). Getting Started 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 button right below where we cloned the repo and . Download 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 tab (Figure 5). items 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 , let’s take a look at what is going on: src/App.js We import the downloaded AppSync configuration file. This file contains the which is the API URL that was provisioned when the API was created from the AppSync dashboard, the , as well as a couple of other pieces of configuration. graphqlEndpoint apiKey from the 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. ApolloProvider Apollo client is similar to the constructor. It takes a configuration object containing the API url, region, and auth information. AWSAppSyncClient ApolloClient is a helper from the library that will basically wait to render the application until the data is fetched from the local cache and the application is wired up with the Rehydrated aws-appsync-react AWSAppSyncClient As mentioned in step 3, here we are passing our unique configuration to the constructor. AWSAppSyncClient Here we create the main application component, wrapping the App component in both the as well as . ApolloProvider Rehydrated Next let’s take a look at and . In these files, you will see a typical GraphQL / Apollo configuration. src/Components/AllEvents.js src/GraphQL/QueryAllEvents.js The GraphQL query in look like this: QueryAllEvents "graphql-tag"; import gql from (`query {listEvents {items {idnamewherewhendescriptioncomments {items {commentId}}}}}`); export default gql 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 along with the query. Event listEvents 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 offer a way to link database tables (in our case, DynamoDB) to individual queries and mutations. Resolvers 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 (VTL) to map GraphQL queries into a format specific to your data source. Velocity Templating Language 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 button in the top right corner of the screen above the data types. Create Resources In the Create Resources screen, choose User as the type from the dropdown menu, and scroll to the bottom and click the button (Figure 10). Create 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 . You should also be able to view the new definitions in the schema. UserTable 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 query. getUser 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 for an overview of Amplify. this YouTube clip 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 as well as the . developer guide 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.
