Set up Amplify GraphQL API

Amplify's GraphQL API category allows you to build a secure, real-time GraphQL API backed by a database in minutes. Define your data model in a GraphQL schema and Amplify will deploy a GraphQL API powered by AWS AppSync, connect to a database powered by Amazon DynamoDB on your behalf. You can secure your API with authorization rules and scale to custom use cases with AWS Lambda.

Creating your first API and database table

Amplify's GraphQL API category can be deployed either using the Amplify CLI or using AWS Cloud Development Kit (CDK). The Amplify Command Line Interface (CLI) is a unified toolchain to create, integrate, and manage the AWS cloud services for your frontend app. The AWS CDK is an open-source Infrastructure-as-Code framework used to model and provision your AWS cloud application resources with familiar programming languages.

amplify add api

? Select from one of the below mentioned services:
> GraphQL
? Here is the GraphQL API that we will create. Select a setting to edit or continue
> Continue
? Choose a schema template:
> Single object with fields (e.g., “Todo” with ID, name, description)
...
Edit your schema at <...>/schema.graphql or place .graphql files in a directory at <...>/schema
✔ Do you want to edit the schema now? (Y/n)
> yes
Edit the file in your editor: <...>/schema.graphql
✅ Successfully added resource new locally

# This "input" configures a global authorization rule to enable public access to
# all models in this schema. Learn more about authorization rules here: https://docs.amplify.aws/react/build-a-backend/graphqlapi/customize-authorization-rules/
input AMPLIFY {
  globalAuthRule: AuthRule = { allow: public }
} # FOR TESTING ONLY!
type Todo @model {
  id: ID!
  name: String!
  description: String
}

npm install @aws-amplify/graphql-api-construct

import {
  AmplifyGraphqlApi,
  AmplifyGraphqlDefinition
} from '@aws-amplify/graphql-api-construct';

export class BackendStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const amplifyApi = new AmplifyGraphqlApi(this, 'AmplifyCdkGraphQlApi', {
      definition: AmplifyGraphqlDefinition.fromFiles(
        path.join(__dirname, 'schema.graphql')
      ),
      authorizationModes: {
        defaultAuthorizationMode: 'API_KEY',
        apiKeyConfig: {
          expires: cdk.Duration.days(30)
        }
      }
    });
  }
}

type Todo @model @auth(rules: [{ allow: public }]) {
  id: ID!
  name: String!
  description: String
}

Every GraphQL type with the @model directive is automatically backed by a new DynamoDB database table and generates create, read, update, and delete GraphQL queries and mutations for you.

Now let's deploy your changes to the cloud:

amplify push -y

cdk deploy

That's it! Your API and database tables are set up.

Setup your app code

To connect your application to your API, we recommend to use the Amplify Library and auto-generated GraphQL client helper code. This gives you the ability to hit the ground running with sensible defaults that you can tweak as your use cases evolve for more optimization.

Install the Amplify Library

Use Amplify libraries to connect your app with your GraphQL endpoint.

Add the Amplify library to your app with npm:

npm install aws-amplify

Configure the Amplify Library in your app code

import { Amplify } from 'aws-amplify';
import { generateClient } from 'aws-amplify/api';
import config from './amplifyconfiguration.json';
Amplify.configure(config);

const client = generateClient();

✨  Deployment time: 62.86s

Outputs:
BackendStack.amplifyApiModelSchemaS3Uri = s3://.../model-schema.graphql
BackendStack.awsAppsyncApiEndpoint = https://wy5mtp7jzfctxc5w5pzkcoktbi.appsync-api.us-east-1.amazonaws.com/graphql
BackendStack.awsAppsyncApiId = YOUR_API_ID_VALUE_HERE
BackendStack.awsAppsyncApiKey = da2-XXXX
BackendStack.awsAppsyncAuthenticationType = API_KEY
BackendStack.awsAppsyncRegion = us-east-1

import { Amplify } from 'aws-amplify';

Amplify.configure({
  API: {
    GraphQL: {
      endpoint: 'https://abcxyz.appsync-api.us-east-1.amazonaws.com/graphql',
      region: 'us-east-1',
      defaultAuthMode: 'apiKey',
      apiKey: 'da2-xxxxxxxxxxxxxxxxxxxxxxxxxx'
    }
  }
});

Generate GraphQL client helper code

npx @aws-amplify/cli codegen add --apiId <YOUR_API_ID> --region <YOUR_API_REGION>

npx @aws-amplify/cli codegen

Add your first record

Next, let's try to query from the GraphQL API. Follow along the steps below to make a query from a React app:

import { generateClient } from 'aws-amplify/api';
import { createTodo, updateTodo, deleteTodo } from './graphql/mutations';
import { listTodos } from './graphql/queries';

Then, create your first todo item with the a GraphQL API call:

const client = generateClient();

const result = await client.graphql({
  query: createTodo,
  variables: {
    input: {
      name: 'My first todo!'
    }
  }
});

Query records from the table

Use the GraphQL query statement to list all todos in your app:

const result = await client.graphql({ query: listTodos });
console.log(result);

You should see the record created above: My first todo!.

Update the record

To update the record use the GraphQL update mutation:

const result = await client.graphql({
  query: updateTodo,
  variables: {
    input: {
      id: '<...>',
      name: 'My first updated todo!'
    }
  }
});
console.log(result);

The result should contain the updated value: My first updated todo!.

Delete a record

Let's clean up your database! Delete the todo by using the delete mutation:

const result = await client.graphql({
  query: deleteTodo,
  variables: {
    input: {
      id: '<...>'
    }
  }
});
console.log(result);

The result output should indicate to you that the record was successfully deleted!

Iterating on your data model using the GraphQL schema

amplify api gql-compile

amplify push

cdk deploy

npx @aws-amplify/cli codegen

The following schema updates require replacement of the underlying DynamoDB table:

1. Removing or renaming a model
2. Modifying the primary key of a model
3. Modifying a Local Secondary Index of a model (only applies to projects with secondaryKeyAsGSI turned off)

When trying to push a schema change with one or more of these updates you will see an error message explaining that you will lose ALL DATA in any table that requires replacement. To confirm you want to continue with the deployment, run:

amplify push --allow-destructive-graphql-schema-updates

Rebuild GraphQL API

When in development, sometimes test data gets in a bad state or you want to make many changes to your schema all at once. In these cases, you may wish to "rebuild" all of the tables backing your schema. To do this, run the following in your Terminal:

amplify rebuild api

cdk destroy
cdk deploy

This will recreate ALL of the tables backing models in your schema. ALL DATA in ALL TABLES will be deleted.

Next steps

Success! You've learned how to create a GraphQL API backed by a database table and also how to run queries and mutations from your app.

There's so much more to discover with Amplify's GraphQL API capabilities. Learn more about:

• How to model your database table and their access patterns
• Secure your API with fine-grained authorization rules
• Create relationships between different database model
• Add custom business logic to the GraphQL API
• Run search and result aggregation queries
• Connect to machine learning services
• Best practice and examples