Getting Started with AWS AppSync for Modern GraphQL APIs

Traditional REST APIs have served us well, but they often come with challenges like over-fetching or under-fetching data. A client either gets more data than it needs or has to make multiple round trips to get all the data it requires. GraphQL solves this by allowing clients to request exactly the data they need, all in a single request.

AWS AppSync is a fully managed service that makes it easy to develop GraphQL APIs. It handles the heavy lifting of securely connecting to data sources like DynamoDB, Lambda, and more. This guide will walk you through creating your first AppSync API from scratch.

The Goal: A Simple Product API

We will build a simple GraphQL API to query for a product by its ID. The data will be stored in a DynamoDB table.

Step 1: Create a DynamoDB Table

First, we need a place to store our data. Go to the DynamoDB console and create a new table named Products with a primary key of id (string).

After creating the table, add a sample item to it:

• id: product-123
• name: "My Awesome Product"
• description: "The best product ever."
• price: 99.99

Step 2: Create the AppSync API and Define the Schema

Now, head to the AWS AppSync console and create a new API. Choose "Build from scratch."

Once the API is created, the first thing you need to do is define your GraphQL schema. The schema defines the types of data and the operations (queries, mutations) available in your API.

In the AppSync console, go to the "Schema" page and enter the following:

type Product {
    id: ID!
    name: String
    description: String
    price: Float
}

type Query {
    getProduct(id: ID!): Product
}

schema {
    query: Query
}

This schema defines:

• A Product type with four fields.
• A Query type with a single operation, getProduct, which takes an id and returns a Product.

Step 3: Attach a Data Source

Next, we need to tell AppSync where to get the data. We'll connect our DynamoDB table as a data source.

1. In the AppSync console, go to the "Data Sources" page.
2. Create a new data source.
3. Choose "Amazon DynamoDB table" and select the Products table you created earlier.
4. Allow AppSync to create a new IAM role that grants it permission to access the table.

Step 4: Configure a Resolver

A resolver is the glue that connects a GraphQL field to a data source. It contains the logic for fetching the data. We need to create a resolver for our getProduct query.

1. On the "Schema" page, find the getProduct(id: ID!): Product field under Query and click "Attach."
2. Select the Products data source you just created.
3. Now, you need to configure the request mapping template and the response mapping template. These templates, written in Velocity Template Language (VTL), transform the GraphQL request into a format the data source understands and then transform the response back into a GraphQL format.

Request Mapping Template:

This template tells AppSync how to query DynamoDB. We'll use a GetItem operation.

{
    "version": "2017-02-28",
    "operation": "GetItem",
    "key": {
        "id": $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

• $ctx.args.id: This accesses the id argument that was passed into the getProduct query.
• $util.dynamodb.toDynamoDBJson(): A utility function that converts the value to the proper DynamoDB JSON format.

Response Mapping Template:

This template simply forwards the result from DynamoDB back to the client.

$util.toJson($ctx.result)

Save the resolver.

Step 5: Run a Query

Your API is now ready to be tested! In the AppSync console, go to the "Queries" page. You can now run a GraphQL query against your new endpoint.

Enter the following query:

query GetAProduct {
  getProduct(id: "product-123") {
    id
    name
    price
  }
}

When you run this query, AppSync will execute your resolver, fetch the data from DynamoDB, and return the result:

{
  "data": {
    "getProduct": {
      "id": "product-123",
      "name": "My Awesome Product",
      "price": 99.99
    }
  }
}

Notice how the response only contains the fields you requested (id, name, and price), even though the item in DynamoDB also has a description field. This is the power of GraphQL!

Conclusion

You've just built a fully functional, serverless GraphQL API with AWS AppSync. This is just the beginning. From here, you can add mutations to modify data, subscriptions for real-time updates, and connect to other data sources like AWS Lambda to run custom business logic.

AppSync provides a powerful and scalable way to build modern APIs, giving your frontend developers the flexibility to get exactly the data they need, when they need it.