@aws-amplify/api-rest 4.0.1-console-preview.b5a42af.0 → 4.0.1-console-preview.9607e4a.0

package/src/apis/server.ts

@@ -0,0 +1,83 @@
+// 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';
+
+/**
+ * GET HTTP request (server-side)
+ */
+export const get = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: GetInput
+): GetOperation =>
+	commonGet(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * POST HTTP request (server-side)
+ */
+export const post = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PostInput
+): PostOperation =>
+	commonPost(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * PUT HTTP request (server-side)
+ */
+export const put = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PutInput
+): PutOperation =>
+	commonPut(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * DELETE HTTP request (server-side)
+ */
+export const del = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: DeleteInput
+): DeleteOperation =>
+	commonDel(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * HEAD HTTP request (server-side)
+ */
+export const head = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: HeadInput
+): HeadOperation =>
+	commonHead(getAmplifyServerContext(contextSpec).amplify, input);
+
+/**
+ * PATCH HTTP request (server-side)
+ */
+export const patch = (
+	contextSpec: AmplifyServer.ContextSpec,
+	input: PatchInput
+): PatchOperation =>
+	commonPatch(getAmplifyServerContext(contextSpec).amplify, input);

package/src/errors/validation.ts

@@ -5,10 +5,16 @@ 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

@@ -2,3 +2,4 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export { isCancelError } from './errors/CancelledError';
+export { get, post, put, del, head, patch } from './apis';

package/src/internals/index.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Amplify } from '@aws-amplify/core';
 
-import { post as internalPost } from '../common/internalPost';
+import { post as internalPost } from '../apis/common/internalPost';
 import { InternalPostInput } from '../types';
 
 /**
@@ -25,4 +25,7 @@ export const post = (input: InternalPostInput) => {
 	return internalPost(Amplify, input);
 };
 
-export { cancel, updateRequestToBeCancellable } from '../common/internalPost';
+export {
+	cancel,
+	updateRequestToBeCancellable,
+} from '../apis/common/internalPost';

package/src/internals/server.ts

@@ -5,7 +5,7 @@ import {
 	getAmplifyServerContext,
 } from '@aws-amplify/core/internals/adapter-core';
 
-import { post as internalPost } from '../common/internalPost';
+import { post as internalPost } from '../apis/common/internalPost';
 import { InternalPostInput } from '../types';
 
 /**
@@ -31,4 +31,7 @@ export const post = (
 	return internalPost(getAmplifyServerContext(contextSpec).amplify, input);
 };
 
-export { cancel, updateRequestToBeCancellable } from '../common/internalPost';
+export {
+	cancel,
+	updateRequestToBeCancellable,
+} from '../apis/common/internalPost';

package/src/server.ts

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

package/src/types/index.ts

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 import { DocumentType } from '@aws-amplify/core/internals/utils';
 
-export type GetOptions = RestApiOptionsBase;
-export type PostOptions = RestApiOptionsBase;
-export type PutOptions = RestApiOptionsBase;
-export type PatchOptions = RestApiOptionsBase;
-export type DeleteOptions = Omit<RestApiOptionsBase, 'body'>;
-export type HeadOptions = Omit<RestApiOptionsBase, 'body'>;
+export type GetInput = ApiInput<RestApiOptionsBase>;
+export type PostInput = ApiInput<RestApiOptionsBase>;
+export type PutInput = ApiInput<RestApiOptionsBase>;
+export type PatchInput = ApiInput<RestApiOptionsBase>;
+export type DeleteInput = ApiInput<Omit<RestApiOptionsBase, 'body'>>;
+export type HeadInput = ApiInput<Omit<RestApiOptionsBase, 'body'>>;
 
 export type GetOperation = Operation<RestApiResponse>;
 export type PostOperation = Operation<RestApiResponse>;
@@ -16,7 +16,10 @@ export type PatchOperation = Operation<RestApiResponse>;
 export type DeleteOperation = Operation<Omit<RestApiResponse, 'body'>>;
 export type HeadOperation = Operation<Omit<RestApiResponse, 'body'>>;
 
-type RestApiOptionsBase = {
+/**
+ * @internal
+ */
+export type RestApiOptionsBase = {
 	headers?: Headers;
 	queryParams?: Record<string, string>;
 	body?: DocumentType | FormData;
@@ -64,12 +67,20 @@ export interface RestApiResponse {
 }
 
 /**
- * Input type of REST API.
  * @internal
  */
 export type ApiInput<Options> = {
+	/**
+	 * Name of the REST API configured in Amplify singleton.
+	 */
 	apiName: string;
+	/**
+	 * Path of the REST API.
+	 */
 	path: string;
+	/**
+	 * Options to overwrite the REST API call behavior.
+	 */
 	options?: Options;
 };
 

package/src/utils/createCancellableOperation.ts

@@ -5,6 +5,7 @@ import { HttpResponse } from '@aws-amplify/core/internals/aws-client-utils';
 import { CancelledError, RestApiError } from '../errors';
 import { Operation } from '../types';
 import { parseRestApiServiceError } from './serviceError';
+import { logger } from './logger';
 
 /**
  * Create a cancellable operation conforming to the internal POST API interface.
@@ -14,46 +15,60 @@ export function createCancellableOperation(
 	handler: () => Promise<HttpResponse>,
 	abortController: AbortController
 ): Promise<HttpResponse>;
+
 /**
  * Create a cancellable operation conforming to the external REST API interface.
  * @internal
  */
 export function createCancellableOperation(
 	handler: (signal: AbortSignal) => Promise<HttpResponse>
-): Promise<HttpResponse>;
+): Operation<HttpResponse>;
 
 /**
  * @internal
  */
 export function createCancellableOperation(
-	handler: (signal?: AbortSignal) => Promise<HttpResponse>,
+	handler:
+		| ((signal: AbortSignal) => Promise<HttpResponse>)
+		| (() => Promise<HttpResponse>),
 	abortController?: AbortController
 ): Operation<HttpResponse> | Promise<HttpResponse> {
 	const isInternalPost = (
-		handler: (signal?: AbortSignal) => Promise<HttpResponse>
+		handler:
+			| ((signal: AbortSignal) => Promise<HttpResponse>)
+			| (() => Promise<HttpResponse>)
 	): handler is () => Promise<HttpResponse> => !!abortController;
-	const signal = abortController?.signal;
+
+	// For creating a cancellable operation for public REST APIs, we need to create an AbortController
+	// internally. Whereas for internal POST APIs, we need to accept in the AbortController from the
+	// callers.
+	const publicApisAbortController = new AbortController();
+	const publicApisAbortSignal = publicApisAbortController.signal;
+	const internalPostAbortSignal = abortController?.signal;
+
 	const job = async () => {
 		try {
 			const response = await (isInternalPost(handler)
 				? handler()
-				: handler(signal));
+				: handler(publicApisAbortSignal));
+
 			if (response.statusCode >= 300) {
-				throw parseRestApiServiceError(response)!;
+				throw await parseRestApiServiceError(response)!;
 			}
 			return response;
-		} catch (error) {
-			if (error.name === 'AbortError' || signal?.aborted === true) {
-				throw new CancelledError({
+		} catch (error: any) {
+			const abortSignal = internalPostAbortSignal ?? publicApisAbortSignal;
+			if (error.name === 'AbortError' || abortSignal?.aborted === true) {
+				const cancelledError = new CancelledError({
 					name: error.name,
-					message: signal.reason ?? error.message,
+					message: abortSignal.reason ?? error.message,
 					underlyingError: error,
 				});
+				logger.debug(error);
+				throw cancelledError;
 			}
-			throw new RestApiError({
-				...error,
-				underlyingError: error,
-			});
+			logger.debug(error);
+			throw error;
 		}
 	};
 
@@ -61,15 +76,18 @@ export function createCancellableOperation(
 		return job();
 	} else {
 		const cancel = (abortMessage?: string) => {
-			if (signal?.aborted === true) {
+			if (publicApisAbortSignal.aborted === true) {
 				return;
 			}
-			abortController?.abort(abortMessage);
+			publicApisAbortController.abort(abortMessage);
 			// Abort reason is not widely support enough across runtimes and and browsers, so we set it
 			// if it is not already set.
-			if (signal?.reason !== abortMessage) {
-				// @ts-expect-error reason is a readonly property
-				signal['reason'] = abortMessage;
+			if (publicApisAbortSignal.reason !== abortMessage) {
+				type AbortSignalWithReasonSupport = Omit<AbortSignal, 'reason'> & {
+					reason?: string;
+				};
+				(publicApisAbortSignal as AbortSignalWithReasonSupport)['reason'] =
+					abortMessage;
 			}
 		};
 		return { response: job(), cancel };

package/src/utils/index.native.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { loadUrlPolyfill } from '@aws-amplify/react-native';
+
+loadUrlPolyfill();
+
+export { createCancellableOperation } from './createCancellableOperation';
+export { resolveCredentials } from './resolveCredentials';
+export { parseSigningInfo } from './parseSigningInfo';
+export { parseRestApiServiceError } from './serviceError';
+export { resolveApiUrl } from './resolveApiUrl';
+export { logger } from './logger';

package/src/utils/index.ts

@@ -3,5 +3,7 @@
 
 export { createCancellableOperation } from './createCancellableOperation';
 export { resolveCredentials } from './resolveCredentials';
-export { parseUrl } from './parseUrl';
+export { parseSigningInfo } from './parseSigningInfo';
 export { parseRestApiServiceError } from './serviceError';
+export { resolveApiUrl } from './resolveApiUrl';
+export { logger } from './logger';

package/src/utils/logger.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Logger } from '@aws-amplify/core/internals/utils';
+
+export const logger = new Logger('RestApis');

package/src/utils/normalizeHeaders.ts

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export const normalizeHeaders = (headers: Record<string, string>) => {
+export const normalizeHeaders = (headers?: Record<string, string>) => {
 	const normalizedHeaders: Record<string, string> = {};
 	for (const key in headers) {
 		normalizedHeaders[key.toLowerCase()] = headers[key];

package/src/utils/{parseUrl.ts → parseSigningInfo.ts}

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { AmplifyClassV6 } from '@aws-amplify/core';
 import {
 	APIG_HOSTNAME_PATTERN,
 	DEFAULT_IAM_SIGNING_REGION,
@@ -8,12 +9,24 @@ import {
 } from './constants';
 
 /**
- * Infer the signing service and region from the given URL. It supports raw API Gateway endpoint and AppSync endpoint.
- * Custom domain is not supported.
+ * Infer the signing service and region from the given URL, and for REST API only, from the Amplify configuration.
+ * It supports raw API Gateway endpoint and AppSync endpoint.
  *
  * @internal
  */
-export const parseUrl = (url: URL) => {
+export const parseSigningInfo = (
+	url: URL,
+	restApiOptions?: {
+		amplify: AmplifyClassV6;
+		apiName: string;
+	}
+) => {
+	const {
+		service: signingService = DEFAULT_REST_IAM_SIGNING_SERVICE,
+		region: signingRegion = DEFAULT_IAM_SIGNING_REGION,
+	} =
+		restApiOptions?.amplify.getConfig()?.API?.REST?.[restApiOptions?.apiName] ??
+		{};
 	const { hostname } = url;
 	const [, service, region] = APIG_HOSTNAME_PATTERN.exec(hostname) ?? [];
 	if (service === DEFAULT_REST_IAM_SIGNING_SERVICE) {
@@ -21,19 +34,19 @@ export const parseUrl = (url: URL) => {
 		// @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-call-api.html
 		return {
 			service,
-			region,
+			region: region ?? signingRegion,
 		};
 	} else if (service === 'appsync-api') {
 		// AppSync endpoint is internally supported because GraphQL operation will send request using POST handler.
 		// example: https://xxxx.appsync-api.us-east-1.amazonaws.com/graphql
 		return {
 			service: 'appsync',
-			region,
+			region: region ?? signingRegion,
 		};
 	} else {
 		return {
-			service: DEFAULT_REST_IAM_SIGNING_SERVICE,
-			region: DEFAULT_IAM_SIGNING_REGION,
+			service: signingService,
+			region: signingRegion,
 		};
 	}
 };

package/src/utils/resolveApiUrl.ts

@@ -0,0 +1,47 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+import {
+	RestApiError,
+	RestApiValidationErrorCode,
+	assertValidationError,
+	validationErrorMap,
+} from '../errors';
+
+/**
+ * Resolve the REST API request URL by:
+ * 1. Loading the REST API endpoint from the Amplify configuration with corresponding API name.
+ * 2. Appending the path to the endpoint.
+ * 3. Merge the query parameters from path and the queryParameter argument which is taken from the public REST API
+ *   options.
+ * 4. Validating the resulting URL string.
+ *
+ * @internal
+ */
+export const resolveApiUrl = (
+	amplify: AmplifyClassV6,
+	apiName: string,
+	path: string,
+	queryParams?: Record<string, string>
+): URL => {
+	const urlStr = amplify.getConfig()?.API?.REST?.[apiName]?.endpoint;
+	assertValidationError(!!urlStr, RestApiValidationErrorCode.InvalidApiName);
+	try {
+		const url = new URL(urlStr + path);
+		if (queryParams) {
+			const mergedQueryParams = new URLSearchParams(url.searchParams);
+			Object.entries(queryParams).forEach(([key, value]) => {
+				mergedQueryParams.set(key, value);
+			});
+			url.search = new URLSearchParams(mergedQueryParams).toString();
+		}
+		return url;
+	} catch (error) {
+		throw new RestApiError({
+			name: RestApiValidationErrorCode.InvalidApiName,
+			...validationErrorMap[RestApiValidationErrorCode.InvalidApiName],
+			recoverySuggestion: `Please make sure the REST endpoint URL is a valid URL string. Got ${urlStr}`,
+		});
+	}
+};

package/src/utils/resolveCredentials.ts

@@ -10,7 +10,7 @@ import { RestApiValidationErrorCode, assertValidationError } from '../errors';
 export const resolveCredentials = async (amplify: AmplifyClassV6) => {
 	const { credentials } = await amplify.Auth.fetchAuthSession();
 	assertValidationError(
-		!!credentials,
+		!!credentials && !!credentials.accessKeyId && !!credentials.secretAccessKey,
 		RestApiValidationErrorCode.NoCredentials
 	);
 	return credentials;

package/src/utils/serviceError.ts

@@ -14,7 +14,7 @@ import { RestApiError } from '../errors';
  */
 export const buildRestApiServiceError = (error: Error): RestApiError => {
 	const restApiError = new RestApiError({
-		name: error.name,
+		name: error?.name,
 		message: error.message,
 		underlyingError: error,
 	});
@@ -23,11 +23,13 @@ export const buildRestApiServiceError = (error: Error): RestApiError => {
 
 export const parseRestApiServiceError = async (
 	response?: HttpResponse
-): Promise<RestApiError & MetadataBearer> => {
+): Promise<(RestApiError & MetadataBearer) | undefined> => {
 	const parsedError = await parseJsonError(response);
-	return parsedError
-		? Object.assign(buildRestApiServiceError(parsedError), {
-				$metadata: parsedError.$metadata,
-		  })
-		: undefined;
+	if (!parsedError) {
+		// Response is not an error.
+		return;
+	}
+	return Object.assign(buildRestApiServiceError(parsedError), {
+		$metadata: parsedError.$metadata,
+	});
 };

package/lib/utils/parseUrl.d.ts

@@ -1,10 +0,0 @@
-/**
- * Infer the signing service and region from the given URL. It supports raw API Gateway endpoint and AppSync endpoint.
- * Custom domain is not supported.
- *
- * @internal
- */
-export declare const parseUrl: (url: URL) => {
-    service: string;
-    region: string;
-};

package/lib/utils/parseUrl.js

@@ -1,41 +0,0 @@
-"use strict";
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseUrl = void 0;
-var tslib_1 = require("tslib");
-var constants_1 = require("./constants");
-/**
- * Infer the signing service and region from the given URL. It supports raw API Gateway endpoint and AppSync endpoint.
- * Custom domain is not supported.
- *
- * @internal
- */
-var parseUrl = function (url) {
-    var _a;
-    var hostname = url.hostname;
-    var _b = tslib_1.__read((_a = constants_1.APIG_HOSTNAME_PATTERN.exec(hostname)) !== null && _a !== void 0 ? _a : [], 3), service = _b[1], region = _b[2];
-    if (service === constants_1.DEFAULT_REST_IAM_SIGNING_SERVICE) {
-        // The configured endpoint is an API Gateway endpoint
-        // @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-call-api.html
-        return {
-            service: service,
-            region: region,
-        };
-    }
-    else if (service === 'appsync-api') {
-        // AppSync endpoint is internally supported because GraphQL operation will send request using POST handler.
-        // example: https://xxxx.appsync-api.us-east-1.amazonaws.com/graphql
-        return {
-            service: 'appsync',
-            region: region,
-        };
-    }
-    else {
-        return {
-            service: constants_1.DEFAULT_REST_IAM_SIGNING_SERVICE,
-            region: constants_1.DEFAULT_IAM_SIGNING_REGION,
-        };
-    }
-};
-exports.parseUrl = parseUrl;

package/lib-esm/utils/parseUrl.d.ts

@@ -1,10 +0,0 @@
-/**
- * Infer the signing service and region from the given URL. It supports raw API Gateway endpoint and AppSync endpoint.
- * Custom domain is not supported.
- *
- * @internal
- */
-export declare const parseUrl: (url: URL) => {
-    service: string;
-    region: string;
-};

package/lib-esm/utils/parseUrl.js

@@ -1,37 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-import { __read } from "tslib";
-import { APIG_HOSTNAME_PATTERN, DEFAULT_IAM_SIGNING_REGION, DEFAULT_REST_IAM_SIGNING_SERVICE, } from './constants';
-/**
- * Infer the signing service and region from the given URL. It supports raw API Gateway endpoint and AppSync endpoint.
- * Custom domain is not supported.
- *
- * @internal
- */
-export var parseUrl = function (url) {
-    var _a;
-    var hostname = url.hostname;
-    var _b = __read((_a = APIG_HOSTNAME_PATTERN.exec(hostname)) !== null && _a !== void 0 ? _a : [], 3), service = _b[1], region = _b[2];
-    if (service === DEFAULT_REST_IAM_SIGNING_SERVICE) {
-        // The configured endpoint is an API Gateway endpoint
-        // @see: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-call-api.html
-        return {
-            service: service,
-            region: region,
-        };
-    }
-    else if (service === 'appsync-api') {
-        // AppSync endpoint is internally supported because GraphQL operation will send request using POST handler.
-        // example: https://xxxx.appsync-api.us-east-1.amazonaws.com/graphql
-        return {
-            service: 'appsync',
-            region: region,
-        };
-    }
-    else {
-        return {
-            service: DEFAULT_REST_IAM_SIGNING_SERVICE,
-            region: DEFAULT_IAM_SIGNING_REGION,
-        };
-    }
-};