AWS AppSync: Getting Started Guide

AppSync was a brand new AWS service when I wrote this post, but even if it has been 20 years since its release, the name still doesn’t give away what it’s really about – and you came here looking to understand just that.

So should you use AppSync?

AppSync is about implementing APIs. Presumably you usually start by choosing a programming language, an API architecture  (is it RESTful? or will you just wing it?), and then you start coding. A lot. Then comes the client-side implementation, which requires extra coding, and many changes to the API schema.

Sponsorships Available

Sponsorships Available

Sponsorships Available

With AppSync there’s not much wiggle room. You will use GraphQL for your schema, your implementation will be neat, the API will be scalable, effective, and productive – and that will be that. If your API requires querying, mutating, or subscribing to changes – GraphQL is for you. If your data storage is backed by DynamoDB, ElasticSearch, or virtually anywhere else – AppSync is for you.

In this post I’ll guide you through a working example that shows you…

How it works

AppSync is a managed serverless HTTP endpoint, which replaces your API Gateway, many of your Lambda functions, your HTTP implementation, and obviously your web servers (did you not go serverless by now?). To do all that, you only define two main components: a GraphQL schema and resolvers. Let’s start with…

GraphQL

In case you’re out of the loop, the long running HTTP/REST architecture is now obsolete. I happened to love REST and promoted it wherever I went, but I didn’t get to mourn for long as I dived into its successor. GraphQL ignores all the rules its predecessor made, allowing among other things: multiple queries/mutations in a single request, efficiently receiving only the data you need, and subscribing to changes – all while having a strict protocol layout and keeping your (in)sanity.

These are all big words, so let’s just implement a super simple rating API and figure it out from there:

From that alone, without a single line of code, you can already tell what the requests and responses are going to look like, here’s an example:

Request:

Response:

Note that you can do multiple actions in a single HTTP request, and all the responses will be returned in a single go. Also – you can request only the data you need (for example, with createRating the only thing we didn’t already know was the id).

This is only a taste, you can learn more about GraphQL in the official site or in this neat video & text guide.

Data Sources & VTL

GraphQL defines something called “resolvers” that tell the implementation how to operate when certain fields are requested (e.g. Query.listRatings and Mutation.createRating). Both the schema and the resolvers are defined by GraphQL, regardless of the specific backend implementation – AppSync in our case. AppSync lets you describe a GraphQL schema and its resolvers, connecting to data sources through the Velocity Template Language – or VTL for short.

Data sources are pretty straight forward – it’s either a supported database or a custom Lambda function that returns any data from any source you like. You can imagine it as the “model” if you came from MVC. VTL is a very simple language that is used by AppSync to let you convert the GraphQL request arguments into what the data source expects (e.g. a “Query” request if you’re using DynamoDB), and then convert the response from the data source back to a GraphQL response. You can imagine it as the “controller” from MVC.

Those were a lot of words, let’s continue our example – assuming our data is backed on DynamoDB, we will start clicking on “Attach” for the following schema fields:

Query.getRating

Request mapping template:

Response mapping template:

Query.listRatings

Request mapping template:

Response mapping template:

Mutation.createRating

Request mapping template:

Response mapping template:

Mutation.deleteRating

Request mapping template:

Response mapping template:

That. Is. It! This API implementation is complete.

If you’ve used DynamoDB you’d recognize the operations above. The operations, $ctx, and $util are supplied by AppSync and are available for you in your VTL code (if you can call it that). AWS did a great job documenting it, and I feel like this “code” segment doesn’t even need explaining – feel free to comment below if you think otherwise.

We can’t really avoid talking a little bit about security right?…

Authorization

Whether you want to restrict access to a resource, or you want to recognize the user making the request, AppSync today gives you a few options for recognizing the client:

Amazon Cognito

That’s the best option if your architecture allows it, since the user pool is dynamic, and you can access the user’s metadata from the VTL code via $context.identity and determine permissions or identity.

IAM Identity

If you’re implementing an internal API that is only used from your account, you can allow specific access via IAM policies. You’ll need to sign your requests with this for example, and then the identity information will be available through $context.identity just like with Amazon Cognito.

API Key

This is the simplest and most restricted method, for a few reasons:

1. Unlike API Gateway, it forces an expiration time for your keys and you can choose your own custom key.
2. It’s not very dynamic, keys must be added via the AWS API and there’s a limited amount.
3. You can’t restrict resources or recognize the client’s identity via $context.identity.

If you do find yourself using this method, it’s as simple as setting the x-api-key HTTP request header.

Custom Authorizers Hack

Apart from API Gateway’s ability to set never-expiring and custom API keys, it also provides a very important feature: to authorize requests with a custom Lambda function. Custom authorizers are important when you use a service like Auth0 or implement your own session management.

The hack is to use API Gateway + Lambda and forward requests to your AppSync endpoint. This gives you the option to authorize the requests with API Gateway’s capabilities – just make sure you sign the forwarded request with the Lambda’s IAM identity and add the original identity as a header (which can be accessed in VTL via $context.request.headers).

Client-side

The client-side is pretty simple and straightforward. You’ve seen what a request and a response looks like, and you can read more at the official GraphQL website about the different possibilities you have for making requests.

So, should YOU use AppSync?

Yes! AppSync is still evolving and requires some enhancements, especially with regards to custom authorizers and other API Gateway features (like throttling), but I’m hopeful I will strikethrough this sentence soon.

If you’re implementing your API backend with API Gateway, or worse – EC2 – you are doing it wrong. Give AppSync a try, the AWS Console comes with pre-made templates and auto-generated schemas, it’s almost ridiculous how little work you have to do.