Wrangling GraphQL Data Schemas with AWS AppSync

What to Do When Your GraphQL Queries & Mutations Won't Auto-Build with AWS AppSync

How's it going everyone? 👋 This is Brian and welcome back to the Tech Stack Playbook, your guide to apps, software and tech (but in a fun way I promise).

In today's blog post, we are going to look at AWS AppSync, GraphQL, and debug an interesting issue I came across last night trying to build my API endpoint for a blog app.

While it's important to know how things work, I continue to be reminded that it is even more important to know why things don't work, and even more so, knowing how to fix issues when they arise.

Here’s a glance at what you’ll learn in this blog post:
👉 How AWS Amplify, AppSync, and GraphQL Transformer work
👉 What to do if you GraphQL queries/mutations won't auto-build
👉 How to test and push your data schema and API to the cloud

What is the AWS Amplify Framework?

One of my absolute favorite frameworks for building full-stack cloud applications is the AWS Amplify Framework. Not only does it support core AWS services across:

• Authentication: AWS Cognito
• Database: DynamoDB
• Storage: AWS S3
• API: AWS AppSync

...But it also supports a powerful way to work with GraphQL - the GraphQL Transformer

AppSync will help you auto-build your queries and mutations based on the schema you define in your schema.graphql file. Not only does this reduce the possibility of errors in production, but it also increases your ability to turn code around faster with code generation (codegen) and auto-build sequences to configure the database, storage, and authentication privileges in the cloud based on your API endpoint in a matter of minutes.

So what happens if you come across an issue where you don't see the /graphql folder in your application?

For reference, I am using the NEXTjs framework, which is why the graphql folder is in the /src folder.

This is the solve for this issue if you aren't getting the queries and mutations in your /src folder...

⚠️ Issue: The GraphQL Mutations and Queries aren't building in your app's root folder.

So after some debugging, I found out that in the /amplify/backend/api/blogapp/cli-inputs.json file, this is where your .json file will point to the schema path.

❌ Initially, I had it pointing to the Trash folder...most likely because I was working on a previous project, put it in the trash, but the amplify pointer was still set to follow where the root project went:

{
  "version": 1,
  "serviceConfiguration": {
    "apiName": "blogapp",
    "serviceName": "AppSync",
    "gqlSchemaPath": "/Users/USERNAME/.Trash/blogapp/amplify/backend/api/blogapp/schema.graphql",
    "defaultAuthType": {
      "mode": "API_KEY",
      "expirationTime": 7
    }
  }
}

✅ To fix this, I re-directed the gqlSchemaPath to the location of the schema.graphql file below (the correct link).

This works so long as it's pointing to the right directory of the project:

{
  "version": 1,
  "serviceConfiguration": {
    "apiName": "blogapp",
    "serviceName": "AppSync",
    "gqlSchemaPath": "/Users/USERNAME/Documents/GitHub/AWSAmplify_GraphQL_Blog/blogapp/amplify/backend/api/blogapp/schema.graphql",
    "defaultAuthType": {
      "mode": "API_KEY",
      "expirationTime": 7
    }
  }
}

⚠️ There was no graphqlconfig.yml file in the root folder of the project

By configuring your project to generate code with codegen, you need a place to store the configuration. The graphqlconfig.yml file is auto-built in the root folder and when generating the types defined in your schema.graphql file, codegen takes in GraphQL statements (inputs) and generates types that can be used based on the schema (outputs).

I initially had a placeholder file:

projects:
  blogapp:
    schemaPath: src/graphql/schema.json
    includes:
      - src/graphql/**/*.js
    excludes:
      - ./amplify/**
    extensions:
      amplify:
        codeGenTarget: javascript
        generatedFileName: ''
        docsFilePath: src/graphql

When I run amplify push later, this auto-generates the file below:

projects:
  blogapp:
    schemaPath: src/graphql/schema.json
    includes:
      - src/graphql/**/*.js
    excludes:
      - ./amplify/**
    extensions:
      amplify:
        codeGenTarget: javascript
        generatedFileName: ''
        docsFilePath: src/graphql
extensions:
  amplify:
    version: 3

Once you have updated your schema and want to update your schema.graphql file, you can run:

amplify api-gql-compile

🛠 Testing

Of course, where would we be without implementing test-driven-development in our development lifecycle?

A recommended flow would be:

• Create/edit the GraphQL schema
• Test the data schema via mocking
• Ensure all specifications and requirements are met
• Push to the cloud and auto-build

With the AWS Amplify framework, testing a GraphQL API endpoint is as easy as running a single command in the terminal:

amplify mock api

Did you learn something new about AWS and the cloud? 💭

Let me know in the comments below! ⬇️

Subscribe to the Tech Stack Playbook on YouTube:

Let me know if you found this post helpful! And if you haven't yet, make sure to check out these free resources below:

• Sign up for my newsletter: Email List
• Follow my Instagram for more: @BrianHHough
• Watch my latest YouTube video for more
• Listen to my Podcast on Apple Podcasts and Spotify