@aws-amplify/api-rest 3.5.6-unstable.7762f1a.0 → 4.0.0

package/src/apis/common/publicApis.ts

@@ -0,0 +1,99 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	GetInput,
+	GetOperation,
+	PostInput,
+	PostOperation,
+	PutInput,
+	PutOperation,
+	DeleteInput,
+	DeleteOperation,
+	HeadInput,
+	HeadOperation,
+	PatchInput,
+	PatchOperation,
+	ApiInput,
+	RestApiOptionsBase,
+} from '../../types';
+import {
+	resolveApiUrl,
+	createCancellableOperation,
+	logger,
+	parseSigningInfo,
+} from '../../utils';
+import { transferHandler } from './handler';
+
+const publicHandler = (
+	amplify: AmplifyClassV6,
+	options: ApiInput<RestApiOptionsBase>,
+	method: string
+) =>
+	createCancellableOperation(async abortSignal => {
+		const { apiName, options: apiOptions = {}, path: apiPath } = options;
+		const url = resolveApiUrl(
+			amplify,
+			apiName,
+			apiPath,
+			apiOptions?.queryParams
+		);
+		const libraryOptionsHeaders =
+			await amplify.libraryOptions?.API?.REST?.headers?.({
+				apiName,
+			});
+		const { headers: invocationHeaders = {} } = apiOptions;
+		const headers = {
+			// custom headers from invocation options should precede library options
+			...libraryOptionsHeaders,
+			...invocationHeaders,
+		};
+		const signingServiceInfo = parseSigningInfo(url, {
+			amplify,
+			apiName,
+		});
+		logger.debug(
+			method,
+			url,
+			headers,
+			`IAM signing options: ${JSON.stringify(signingServiceInfo)}`
+		);
+		return transferHandler(
+			amplify,
+			{
+				...apiOptions,
+				url,
+				method,
+				headers,
+				abortSignal,
+			},
+			signingServiceInfo
+		);
+	});
+
+export const get = (amplify: AmplifyClassV6, input: GetInput): GetOperation =>
+	publicHandler(amplify, input, 'GET');
+
+export const post = (
+	amplify: AmplifyClassV6,
+	input: PostInput
+): PostOperation => publicHandler(amplify, input, 'POST');
+
+export const put = (amplify: AmplifyClassV6, input: PutInput): PutOperation =>
+	publicHandler(amplify, input, 'PUT');
+
+export const del = (
+	amplify: AmplifyClassV6,
+	input: DeleteInput
+): DeleteOperation => publicHandler(amplify, input, 'DELETE');
+
+export const head = (
+	amplify: AmplifyClassV6,
+	input: HeadInput
+): HeadOperation => publicHandler(amplify, input, 'HEAD');
+
+export const patch = (
+	amplify: AmplifyClassV6,
+	input: PatchInput
+): PatchOperation => publicHandler(amplify, input, 'PATCH');

package/src/apis/index.ts

@@ -0,0 +1,239 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+import {
+	get as commonGet,
+	post as commonPost,
+	put as commonPut,
+	del as commonDel,
+	head as commonHead,
+	patch as commonPatch,
+} from './common/publicApis';
+import {
+	DeleteInput,
+	DeleteOperation,
+	GetInput,
+	GetOperation,
+	HeadInput,
+	HeadOperation,
+	PatchInput,
+	PatchOperation,
+	PostInput,
+	PostOperation,
+	PutInput,
+	PutOperation,
+} from '../types';
+import { RestApiError } from '../errors';
+
+/**
+ * GET HTTP request
+ * @param {GetInput} input - Input for GET operation
+ * @returns {GetOperation} Operation for GET request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a GET request
+ * ```js
+ * import { get, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await get({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a GET request
+ *
+ * ```js
+ * import { get, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = get({apiName, path, options});
+ * cancel(message);
+ * try {
+ *   await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *    // handle request cancellation
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+export const get = (input: GetInput): GetOperation => commonGet(Amplify, input);
+
+/**
+ * POST HTTP request
+ * @param {PostInput} input - Input for POST operation
+ * @returns {PostOperation} Operation for POST request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a POST request
+ * ```js
+ * import { post, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await post({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a POST request
+ *
+ * ```js
+ * import { post, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = post({apiName, path, options});
+ * cancel(message);
+ * try {
+ *   await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *    // handle request cancellation
+ *   }
+ *   //...
+ * }
+ * ```
+ */
+export const post = (input: PostInput): PostOperation =>
+	commonPost(Amplify, input);
+
+/**
+ * PUT HTTP request
+ * @param {PutInput} input - Input for PUT operation
+ * @returns {PutOperation} Operation for PUT request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PUT request
+ * ```js
+ * import { put, isCancelError } from '@aws-amplify/api';
+ *
+ * const { body } = await put({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ * @example
+ * Cancel a PUT request
+ * ```js
+ * import { put, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = put({apiName, path, options});
+ * cancel(message);
+ * try {
+ *  await response;
+ * } cache (e) {
+ *   if (isCancelError(e)) {
+ *     // handle request cancellation
+ *   }
+ * //...
+ * }
+ * ```
+ */
+export const put = (input: PutInput): PutOperation => commonPut(Amplify, input);
+
+/**
+ * DELETE HTTP request
+ * @param {DeleteInput} input - Input for DELETE operation
+ * @returns {DeleteOperation} Operation for DELETE request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a DELETE request
+ * ```js
+ * import { del } from '@aws-amplify/api';
+ *
+ * const { statusCode } = await del({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * ```
+ */
+export const del = (input: DeleteInput): DeleteOperation =>
+	commonDel(Amplify, input);
+
+/**
+ * HEAD HTTP request
+ * @param {HeadInput} input - Input for HEAD operation
+ * @returns {HeadOperation} Operation for HEAD request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a HEAD request
+ * ```js
+ * import { head, isCancelError } from '@aws-amplify/api';
+ *
+ * const { headers, statusCode } = await head({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }),response;
+ * ```
+ *
+ */
+export const head = (input: HeadInput): HeadOperation =>
+	commonHead(Amplify, input);
+
+/**
+ * PATCH HTTP request
+ * @param {PatchInput} input - Input for PATCH operation
+ * @returns {PatchOperation} Operation for PATCH request
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PATCH request
+ * ```js
+ * import { patch } from '@aws-amplify/api';
+ *
+ * const { body } = await patch({
+ *   apiName,
+ *   path,
+ *   options: {
+ *     headers, // Optional, A map of custom header key/values
+ *     body, // Optional, JSON object or FormData
+ *     queryParams, // Optional, A map of query strings
+ *   }
+ * }).response;
+ * const data = await body.json();
+ * ```
+ *
+ * @example
+ * Cancel a PATCH request
+ * ```js
+ * import { patch, isCancelError } from '@aws-amplify/api';
+ *
+ * const { response, cancel } = patch({apiName, path, options});
+ * cancel(message);
+ * try {
+ *  await response;
+ * } cache (e) {
+ *  if (isCancelError(e)) {
+ *   // handle request cancellation
+ *  }
+ * //...
+ * }
+ * ```
+ */
+export const patch = (input: PatchInput): PatchOperation =>
+	commonPatch(Amplify, input);

package/src/apis/server.ts

@@ -0,0 +1,209 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AmplifyServer,
+	getAmplifyServerContext,
+} from '@aws-amplify/core/internals/adapter-core';
+import {
+	get as commonGet,
+	post as commonPost,
+	put as commonPut,
+	del as commonDel,
+	head as commonHead,
+	patch as commonPatch,
+} from './common/publicApis';
+import {
+	DeleteInput,
+	DeleteOperation,
+	GetInput,
+	GetOperation,
+	HeadInput,
+	HeadOperation,
+	PatchInput,
+	PatchOperation,
+	PostInput,
+	PostOperation,
+	PutInput,
+	PutOperation,
+} from '../types';
+import { RestApiError } from '../errors';
+
+/**
+ * GET HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {GetInput} input - Input for GET operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a GET request
+ * ```js
+ * import { get } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { body } = await get(contextSpec, input).response;
+ *       return await body.json();
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ * @see {@link clientGet}
+ */
+export const get = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: GetInput
+): GetOperation =>
+	commonGet(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * POST HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {PostInput} input - Input for POST operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a POST request
+ * ```js
+ * import { post } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { body } = await post(contextSpec, input).response;
+ *       return await body.json();
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export const post = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PostInput
+): PostOperation =>
+	commonPost(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * PUT HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {PutInput} input - Input for PUT operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PUT request
+ * ```js
+ * import { put } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { body } = await put(contextSpec, input).response;
+ *       return await body.json();
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export const put = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PutInput
+): PutOperation =>
+	commonPut(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * DELETE HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {DeleteInput} input - Input for DELETE operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a DELETE request
+ * ```js
+ * import { del } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { headers } = await del(contextSpec, input).response;
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export const del = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: DeleteInput
+): DeleteOperation =>
+	commonDel(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * HEAD HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {HeadInput} input - Input for HEAD operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a HEAD request
+ * ```js
+ * import { head } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { headers } = await head(contextSpec, input).response;
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export const head = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: HeadInput
+): HeadOperation =>
+	commonHead(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * PATCH HTTP request (server-side)
+ * @param {AmplifyServer.ContextSpec} contextSpec - The context spec used to get the Amplify server context.
+ * @param {PatchInput} input - Input for PATCH operation.
+ * @throws - {@link RestApiError}
+ * @example
+ * Send a PATCH request
+ * ```js
+ * import { patch } from 'aws-amplify/api/server';
+ * //...
+ * const restApiResponse = await runWithAmplifyServerContext({
+ *   nextServerContext: { request, response },
+ *   operation: async (contextSpec) => {
+ *     try {
+ *       const { body } = await patch(contextSpec, input).response;
+ *       return await body.json();
+ *     } catch (error) {
+ *       console.log(error);
+ *       return false;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export const patch = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PatchInput
+): PatchOperation =>
+	commonPatch(getAmplifyServerContext(contextSpec).amplify, input);

package/src/errors/CanceledError.ts

@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyErrorParams } from '@aws-amplify/core/internals/utils';
+import { RestApiError } from './RestApiError';
+
+/**
+ * Internal-only class for CanceledError.
+ *
+ * @internal
+ */
+export class CanceledError extends RestApiError {
+	constructor(params: Partial<AmplifyErrorParams> = {}) {
+		super({
+			name: 'CanceledError',
+			message: 'Request is canceled by user',
+			...params,
+		});
+
+		// TODO: Delete the following 2 lines after we change the build target to >= es2015
+		this.constructor = CanceledError;
+		Object.setPrototypeOf(this, CanceledError.prototype);
+	}
+}
+
+/**
+ * Check if an error is caused by user calling `cancel()` in REST API.
+ *
+ * @note This function works **ONLY** for errors thrown by REST API. For GraphQL APIs, use `client.isCancelError(error)`
+ *   instead. `client` is generated from  `generateClient()` API from `aws-amplify/api`.
+ */
+export const isCancelError = (error: unknown): error is CanceledError =>
+	!!error && error instanceof CanceledError;

package/src/errors/RestApiError.ts

@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AmplifyError,
+	AmplifyErrorParams,
+} from '@aws-amplify/core/internals/utils';
+
+export class RestApiError extends AmplifyError {
+	constructor(params: AmplifyErrorParams) {
+		super(params);
+
+		// TODO: Delete the following 2 lines after we change the build target to >= es2015
+		this.constructor = RestApiError;
+		Object.setPrototypeOf(this, RestApiError.prototype);
+	}
+}

package/src/errors/assertValidatonError.ts

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { RestApiError } from './RestApiError';
+import { RestApiValidationErrorCode, validationErrorMap } from './validation';
+
+/**
+ * @internal
+ */
+export function assertValidationError(
+	assertion: boolean,
+	name: RestApiValidationErrorCode
+): asserts assertion {
+	const { message, recoverySuggestion } = validationErrorMap[name];
+
+	if (!assertion) {
+		throw new RestApiError({ name, message, recoverySuggestion });
+	}
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { CanceledError, isCancelError } from './CanceledError';
+export { RestApiError } from './RestApiError';
+export { assertValidationError } from './assertValidatonError';
+export { RestApiValidationErrorCode, validationErrorMap } from './validation';

package/src/errors/validation.ts

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyErrorMap } from '@aws-amplify/core/internals/utils';
+
+export enum RestApiValidationErrorCode {
+	NoCredentials = 'NoCredentials',
+	InvalidApiName = 'InvalidApiName',
+}
+
+export const validationErrorMap: AmplifyErrorMap<RestApiValidationErrorCode> = {
+	[RestApiValidationErrorCode.NoCredentials]: {
+		message: 'Credentials should not be empty.',
+	},
+	[RestApiValidationErrorCode.InvalidApiName]: {
+		message: 'API name is invalid.',
+		recoverySuggestion:
+			'Check if the API name matches the one in your configuration or `aws-exports.js`',
+	},
+};

package/src/index.ts

@@ -1,5 +1,5 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { RestAPI, RestAPIClass } from './RestAPI';
-export { RestClient } from './RestClient';
+export { isCancelError } from './errors/CanceledError';
+export { get, post, put, del, head, patch } from './apis';

package/src/internals/index.ts

@@ -0,0 +1,31 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Amplify } from '@aws-amplify/core';
+
+import { post as internalPost } from '../apis/common/internalPost';
+import { InternalPostInput } from '../types';
+
+/**
+ * Internal-only REST POST handler to send GraphQL request to given endpoint. By default, it will use IAM to authorize
+ * the request. In some auth modes, the IAM auth has to be disabled. Here's how to set up the request auth correctly:
+ * * If auth mode is 'iam', you MUST NOT set 'authorization' header and 'x-api-key' header, since it would disable IAM
+ *   auth. You MUST also set 'input.options.signingServiceInfo' option.
+ *   * The including 'input.options.signingServiceInfo.service' and 'input.options.signingServiceInfo.region' are
+ *     optional. If omitted, the signing service and region will be inferred from url.
+ * * If auth mode is 'none', you MUST NOT set 'options.signingServiceInfo' option.
+ * * If auth mode is 'apiKey', you MUST set 'x-api-key' custom header.
+ * * If auth mode is 'oidc' or 'lambda' or 'userPool', you MUST set 'authorization' header.
+ *
+ * To make the internal post cancellable, you must also call `updateRequestToBeCancellable()` with the promise from
+ * internal post call and the abort controller supplied to the internal post call.
+ *
+ * @internal
+ */
+export const post = (input: InternalPostInput) => {
+	return internalPost(Amplify, input);
+};
+
+export {
+	cancel,
+	updateRequestToBeCancellable,
+} from '../apis/common/internalPost';