Create, update, and delete application data

In this guide, you will learn how to create, update, and delete your data using Amplify Libraries' GraphQL client.

Before you begin, you will need:

• An application connected to the API

Run mutations to create, update, and delete application data

In GraphQL, mutations are APIs that are used to create, update, or delete data. This is different than queries, which are used to read the data but not change it. The following examples demonstrate how you can create, update, and delete items using the Amplify GraphQL client.

Create an item

You can create an item by first importing the API and mutations. Then you can add an item:

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';
import { GraphQLQuery } from '@aws-amplify/api';
import { CreateTodoInput, CreateTodoMutation } from './API';

const todoDetails: CreateTodoInput = {
  name: 'Todo 1',
  description: 'Learn AWS AppSync'
};

const newTodo = await API.graphql<GraphQLQuery<CreateTodoMutation>>({
  query: mutations.createTodo,
  variables: { input: todoDetails }
});

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';

const todoDetails = {
  name: 'Todo 1',
  description: 'Learn AWS AppSync'
};

const newTodo = await API.graphql({
  query: mutations.createTodo,
  variables: { input: todoDetails }
});

Update an item

To update the item, use the GraphQL update mutation:

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';
import { GraphQLQuery } from '@aws-amplify/api';
import { UpdateTodoInput, UpdateTodoMutation } from './API';

const todoDetails: UpdateTodoInput = {
  id: 'some_id',
  description: 'Updated description'
};

const updatedTodo = await API.graphql<GraphQLQuery<UpdateTodoMutation>>({
  query: mutations.updateTodo,
  variables: { input: todoDetails }
});

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';

const todoDetails = {
  id: 'some_id',
  //  _version: 'current_version', // add the "_version" field if your AppSync API has conflict detection (required for DataStore) enabled
  description: 'Updated description'
};

const updatedTodo = await API.graphql({
  query: mutations.updateTodo,
  variables: { input: todoDetails }
});

Delete an item

You can then delete the Todo by using the delete mutation. To specify which item to delete, you only need to provide the id of that item:

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';
import { GraphQLQuery } from '@aws-amplify/api';
import { DeleteTodoInput, DeleteTodoMutation } from './API';

const todoDetails: DeleteTodoInput = {
  id: 'some_id'
};

const deletedTodo = await API.graphql<GraphQLQuery<DeleteTodoMutation>>({
  query: mutations.deleteTodo,
  variables: { input: todoDetails }
});

import { API } from 'aws-amplify';
import * as mutations from './graphql/mutations';

const todoDetails = {
  id: 'some_id'
};

const deletedTodo = await API.graphql({
  query: mutations.deleteTodo,
  variables: { input: todoDetails }
});

import { API } from 'aws-amplify';
import { GraphQLQuery, GRAPHQL_AUTH_MODE } from '@aws-amplify/api';
import * as mutations from './graphql/mutations';
import { CreateTodoInput, CreateTodoMutation } from './API';

const todoDetails: CreateTodoInput = {
  id: 'some_id',
  name: 'My todo!',
  description: 'Hello world!'
};

const todo = await API.graphql<GraphQLQuery<CreateTodoMutation>>({
  query: mutations.createTodo,
  variables: { input: todoDetails },
  authMode: GRAPHQL_AUTH_MODE.AWS_IAM
});

import { API } from 'aws-amplify';
import { GRAPHQL_AUTH_MODE } from '@aws-amplify/api';
import * as mutations from './graphql/mutations';

const todoDetails = {
  id: 'some_id',
  name: 'My todo!',
  description: 'Hello world!'
};

const todo = await API.graphql({
  query: mutations.createTodo,
  variables: { input: todoDetails },
  authMode: GRAPHQL_AUTH_MODE.AWS_IAM
});

Cancel mutation requests

You can cancel any GraphQL API request by calling .cancel on the GraphQL request promise that's returned by API.graphql(...).

const promise = API.graphql({ query: "..." });

try {
  await promise;
} catch (error) {
  console.log(error);
  // If the error is because the request was cancelled you can confirm here.
  if (API.isCancel(error)) {
    console.log(error.message); // "my message for cancellation"
    // handle user cancellation logic
  }
}

...

// To cancel the above request
API.cancel(promise, "my message for cancellation");

You need to ensure that the promise returned from API.graphql() has not been modified. Typically, async functions wrap the promise being returned into another promise. For example, the following will not work:

async function makeAPICall() {
  return API.graphql({ query: '...' });
}
const promise = makeAPICall();

// The following will NOT cancel the request.
API.cancel(promise, 'my error message');

Conclusion

Congratulations! You have finished the Create, update, and delete application data guide. In this guide, you created, updated, and deleted your app data through the GraphQL API.

Next steps

Our recommended next steps include using the API to query data and subscribe to real-time events to look for mutations in your data. Some resources that will help with this work include:

• Read application data
• Subscribe to real-time events