March of the titan

AWS continues its march across the Infrastructure-as-a-Service (Iaas) world with new services coming out each month. When evaluating these services, Engineers and Architects are called to make difficult decisions that balance vendor lock-in, standards, likely future adoption, maintainability and cost.

Function over form

Crucially the need to deliver a product, quickly, reliably and scalably trumps the academic pursuit of the perfect tech or new-phoric love of the latest trend. If there’s an AWS service - read global, pay-as-you-go, massively scalable, low barrier to entry - that helps you to do what you’re trying to do online, then surely it’s worth evaluating.

Embrace the new

AppSync promises to do exactly that. Coupled with some good infrastructure-as-code, it reduces the complexity associated with setting up a GraphQL API and backing datastore to a few well ordered lines of Terraform code.



Let’s start with a basic type in GraphQL

# Docs
type Doc {
    created: Int!
    creatorAccountId: String!
    id: ID!
    body: String!

then a connection to read streams of them and some CRUD param lists

type DocConnection {
    items: [Doc]
    nextToken: String

input CreateDocInput {
    creatorAccountId: String!
    body: String!

input UpdateDocInput {
    id: ID!
    body: String

input DeleteDocInput {
    id: ID!

We need a query to read the latest docs, mutations to update them and subscriptions to listen for changes:

type Query {
        creatorAccountId: String,
        limit: Int,
        nextToken: String
    ): DocConnection

type Mutation {
    createDoc(input: CreateDocInput!): Doc
    updateDoc(input: UpdateDocInput!): Doc
    deleteDoc(input: DeleteDocInput!): Doc

type Subscription {
    onCreateDoc(creatorAccountId: String!): Doc
    @aws_subscribe(mutations: ["createDoc"])
    onUpdateDoc(id: ID, body: String): Doc
    @aws_subscribe(mutations: ["updateDoc"])
    onDeleteDoc(id: ID, body: String): Doc
    @aws_subscribe(mutations: ["deleteDoc"])

Finally we want a top-level schema to tell GraphQL about all these bits:

schema {
    query: Query
    mutation: Mutation
    subscription: Subscription


Next we’re going to need some Terraform code to provision it. First we create an AppSync API:

provider "aws" {
  region = "eu-west-1"
  alias = "ireland"
resource "aws_appsync_graphql_api" "grapple" {
  name = "grapple-${terraform.workspace}-${var.project_name}"
  authentication_type = "API_KEY"
  provider = "aws.ireland"

At the time of writing AppSync wasn’t available in eu-west-2 (London) so we’re using eu-west-1 (Ireland). Now we need an API key to access it:

resource "aws_appsync_api_key" "api_key" {
  api_id = "${}"
  # API keys have a maximum validity period of 365 days
  expires = "2020-01-04T13:00:00Z"
  provider = "aws.ireland"

Once we’ve got an API, we can upload our new schema to it:

# upload schema from template file
data "template_file" "grapple_schema" {
  template = "${file("${path.root}/../../appsync/grapple/schema.graphql")}"
resource "null_resource" "grapple_upload_schema" {
  provisioner "local-exec" {
    command = "aws appsync start-schema-creation --region ${var.aws_region_appsync} --api-id ${} --definition '${data.template_file.grapple_schema.rendered}'"
  # trigger based on changes to the schema
  triggers = {
    file_changes = "${md5(data.template_file.grapple_schema.rendered )}"
  depends_on = ["aws_appsync_graphql_api.grapple"]

The use of a trigger here means that whenever our API file changes locally, it will be re-uploaded to AWS in the next terraform apply.

To be continued

If you want to see more of this kind of material, just drop me an email and I’d be happy to expand it here.

Leave a Comment