A first look at how to build client side GraphQL applications using AWS Amplify.
View AWS Amplify GraphQL docs here.
In the rapidly evolving GraphQL ecosystem there are several popular GraphQL clients available today including the Apollo Client, URQL, and Lokka.
In the process of developing a way to work more seamlessly with AWS’ managed GraphQL service AWS AppSync, the AWS team created a new GraphQL client.
Because it works great with virtually any GraphQL API or service, they have also decided to open source it. The AWS Amplify GraphQL client offers a simple API, designed to get up and running quicker with little configuration.
The AWS Amplify GraphQL client was released at React Amsterdam along with the general availability of AWS AppSync.
The AWS Amplify GraphQL client supports mutations, subscriptions, & queries & is actively being developed. If you have a feature request or experience a bug, feel free to submit an issue.
We still support our AppSync Apollo SDK for more advanced use cases such as caching & offline support. If you’re interested in those features, check out the Apollo Client for general GraphQL APIs or the AWS AppSync Apollo SDK for use with an AWS AppSync API.
Let’s take a glance at the API.
Setup
To get started, you first need to install the AWS Amplify library:
npm i aws-amplify || yarn add aws-amplify
Next, you will need to add your GraphQL endpoint:
import Amplify from "aws-amplify"
Amplify.configure({ API: { graphql_endpoint: 'https:/www.example.com/my-graphql-endpoint' }})
If you would like to set custom headers, you can just add this to the configure method as well:
Amplify.configure({ API: { graphql_endpoint: 'https:/www.example.com/my-graphql-endpoint', graphql_headers: async () => ({ 'My-Custom-Header': 'my value' }) }});
Setting up a GraphQL API
If you don’t already have one, setting up a GraphQL API can be done in just a couple of minutes with AWS AppSync, including launching a sample schema. Check out the Quickstart here: https://docs.aws.amazon.com/appsync/latest/devguide/quickstart.html
If you’re setting up the client with AppSync, you’ll need the following configuration instead:
let myAppConfig = { 'aws_appsync_graphqlEndpoint': 'https://xxxxxx.appsync-api.us-east-1.amazonaws.com/graphql', 'aws_appsync_region': 'us-east-1', 'aws_appsync_authenticationType': 'API_KEY', 'aws_appsync_apiKey': 'da2-xxxxxxxxxxxxxxxxxxxxxxxxxx'}
Amplify.configure(aws_config)
Queries
To create a query, you need to do two things: define the query, and perform the GraphQL operation.
-
Defining the query using template literals:
const ListEvents =
query ListEvents { listEvents { items { id where description } }}
2. Performing the GraphQL operation:
import { API, graphqlOperation } from 'aws-amplify'
const allEvents = await API.graphql(graphqlOperation(ListEvents))
Adding parameters:
const oneEvent = await API.graphql(graphqlOperation(GetEvent, { id: 'some id' }))
Mutations
Creating mutations is pretty straightforward, we still only need two methods from Amplify: graphqlOperation & API.graphql
Defining the GraphQL mutation using template literals:
const CreateEvent = `mutation CreateEvent($name: String!, $when: String!, $where: String!, $description: String!) { createEvent(name: $name, when: $when, where: $where, description: $description) { id name where when description }}`;
Performing the GraphQL operation:
import { API, graphqlOperation } from 'aws-amplify'
const eventDetails = { name: 'Party tonight!', when: '8:00pm', where: 'Ballroom', decription: 'Coming together as a team!'};const newEvent = await API.graphql(graphqlOperation(CreateEvent, eventDetails));
Subscriptions
Subscriptions are pretty easy to set up as well!
Again, just like the previous two examples, all you need to do is set up your subscription definition and call the GraphQL operation.
Defining the subscription:
const SubscribeToEvents = `subscription subscribeToEvents { subscribeToEvents { id name when where }}`
Creating the subscription:
const subscription = API.graphql( graphqlOperation(SubscribeToEvents)).subscribe({ next: (eventData) => console.log(eventData)});
Now, whenever a new event is created in our API, the next function will fire with the new data!
You can also unsubscribe by calling the unsubscribe method on the new subscription:
subscription.unsubscribe()
React components
Many developers especially in the React ecosystem have come to prefer working with components when possible. AWS also added React components to perform these operations. These are part of the aws-amplify-react package.
To get started with these components, first install aws-amplify-react:
npm i aws-amplify-react || yarn add aws-amplify-react
Next, we can perform a query like so:
import { Connect } from 'aws-amplify-react'
const ListEvents = `query ListEvents { listEvents { items { id name description } }}`
// in your render method:<Connect query={graphqlOperation(ListEvents)}> {({ data: { listEvents } }) => ( <ListView events={listEvents.items} /> )} </Connect>
Subscriptions & mutations work in the same way, to see a detailed explanation of both subscriptions & mutations check out the documentation.
Conclusion
In addition to GraphQL, AWS Amplify is a library that supports a lot of other functionality including authentication, storage, analytics, internationalization, & pub-sub.
To learn more about AWS Amplify, check out the docs or ping me on Twitter.
Thanks for reading!
My Name is Nader Dabit . I am a Developer Advocate at AWS Mobile working with projects like AppSync and AWS Amplify, and the founder of React Native Training.
If you enjoyed this article, please clap n number of times and share it! Thanks for your time.
The opinions expressed herein are my own
Images courtesy of Amazon Web Services, Inc