Migrate from v5 to v6

Like many of our categories in v6, API (REST) has moved to a functional approach in an effort to maintain a smaller bundle size and better tree-shaking. We are also using named params and strict typing for clarity and consistency.

For v6 REST APIs, all API's use the same underlying input/output types, although delete and head both omit the body option.

Note: Setting response to true in v5 will result in the full response object being returned, including headers. If response is set to false or left undefined, the library returns the parsed JS object from the JSON response. In v6, the return object structure is always the same. (expand Output for details)

Input

1apiName: string
2path: string
3init: { // actually { [key: string]: any }, but the values below are expected
4  headers?: { [key: string]: any };
5  body?: any;
6  response?: boolean;
7  queryStringParameters?: { [key: string]: any };
8  withCredentials?: boolean; // allow cross-site Access-Control requests with credentials
9}

1input: {
2  apiName: string;
3  path: string;
4  options?: {
5    headers?: { [x: string]: string; };
6    queryParams?: Record<string, string>;
7    body?: DocumentType | FormData;
8    withCredentials?: boolean; // allow cross-site Access-Control requests with credentials
9  };
10}

Output

1// `response`: true
2// response object interface conforming to Axios library
3{
4  data: any
5  status: number;
6  statusText: string;
7  headers: AxiosResponseHeaders;
8  config: InternalAxiosRequestConfig;
9  request: any
10}
11
12// `response`: false || undefined
13// JSON response deserialized into an object
14{ [key: string]: any }

1{
2  response: Promise<RestApiResponse>;
3  cancel: (abortMessage?: string) => void;
4};
5
6// RestApiResponse
7{
8  body: {
9    blob: () => Promise<Blob>;
10    json: () => Promise<DocumentType>; // Type representing a plain JavaScript object that can be serialized to JSON.
11    text: () => Promise<string>;
12  };
13  statusCode: number;
14  headers: Headers;
15}

API.get

1import { get } from 'aws-amplify/api';
2
3const handleGet = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await get({
15    apiName,
16    path,
17    options: {
18      headers,
19      queryParams,
20    }
21  }).response;
22}

1import { API } from 'aws-amplify'
2
3const handleGet = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await API.get(apiName, path, {
15    headers,
16    // response: true, // add to get full axios details
17    queryStringParameters: queryParams
18  });
19}

API.post

1import { post } from 'aws-amplify/api';
2
3const handlePost = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await post({
17    apiName,
18    path,
19    options: {
20      body,
21      headers,
22      queryParams
23    }
24  }).response;
25}

1import { API } from 'aws-amplify'
2
3const handlePost = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await API.post(apiName, path, {
17    body,
18    headers,
19    queryStringParameters: queryParams
20  });
21}

API.put

1import { put } from 'aws-amplify/api';
2
3const handlePut = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await put({
17    apiName,
18    path,
19    options: {
20      body,
21      headers,
22      queryParams
23    }
24  }).response;
25}

1import { API } from 'aws-amplify'
2
3const handlePost = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await API.put(apiName, path, {
17    body,
18    headers,
19    queryStringParameters: queryParams
20  });
21}

API.del

1import { del } from 'aws-amplify/api';
2
3const handleDelete = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await del({
15    apiName,
16    path,
17    options: {
18      headers,
19      queryParams
20    }
21  }).response;
22}

1import { API } from 'aws-amplify'
2
3const handlePost = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await API.del(apiName, path, {
15    headers,
16    queryStringParameters: queryParams
17  });
18}

API.patch

1import { patch } from 'aws-amplify/api';
2
3const handlePatch = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await patch({
17    apiName,
18    path,
19    options: {
20      body,
21      headers,
22      queryParams
23    }
24  }).response;
25}

1import { API } from 'aws-amplify'
2
3const handlePatch = async ({
4  apiName,
5  path,
6  headers,
7  body,
8  queryParams
9}: {
10  apiName: string,
11  path: string,
12  headers: { [key: string]: any },
13  body: string,
14  queryParams: { [key: string]: any }
15}) => {
16  const response = await API.patch(apiName, path, {
17    body,
18    headers,
19    queryStringParameters: queryParams
20  });
21}

API.head

1import { head } from 'aws-amplify/api';
2
3const handleHead = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await head({
15    apiName,
16    path,
17    options: {
18      headers,
19      queryParams
20    }
21  }).response;
22}

1import { API } from 'aws-amplify'
2
3const handleHead = async ({
4  apiName,
5  path,
6  headers,
7  queryParams
8}: {
9  apiName: string,
10  path: string,
11  headers: { [key: string]: any },
12  queryParams: { [key: string]: any }
13}) => {
14  const response = await API.head(apiName, path, {
15    headers,
16    queryStringParameters: queryParams
17  });
18}

API.cancel

The process for cancelling a request has changed in v6. In v5 you send in the promise as input to the API.cancel API. In v6, cancel is a function returned with the result of an API(REST) operation. To cancel an operation, you will call operation.cancel().

1import { get, isCancelError } from 'aws-amplify/api'
2
3const operation = get({
4  apiName,
5  path,
6  options
7});
8
9operation.response.then(result => {
10  // GET operation completed successfully
11}).catch(error => {
12  // If the error is because the request was cancelled you can confirm here.
13  if(isCancelError(error)) {
14    // 'my message for cancellation'
15    console.log(error.message);
16  }
17})
18
19// To cancel the above request
20operation.cancel('my message for cancellation');

1import { API } from 'aws-amplify'
2
3const promise = API.get(
4  apiName, 
5  path, 
6  options
7);
8
9promise.then(result => {
10  // GET operation completed successfully
11}).catch(error => {
12  // If the error is because the request was cancelled you can confirm here.
13  if(API.isCancel(error)) {
14    // 'my message for cancellation'
15    console.log(error.message);
16  }
17});
18
19// To cancel the above request
20API.cancel(promise, 'my message for cancellation');

Override Amplify-generated API Gateway resources