REST API Methods

/**
 * Performs HTTP GET request
 * @param input - Request configuration including API name and path
 * @returns GetOperation promise that resolves to response
 */
function get(input: GetInput): GetOperation;

interface GetInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface GetOperation {
  response: Promise<RestApiResponse>;
  cancel(abortMessage?: string): void;
}

import { get } from "@aws-amplify/api";

// Simple GET request
const { response } = get({
  apiName: "myRestApi",
  path: "/users/123"
});
const result = await response;

// GET with query parameters and headers
const { response } = get({
  apiName: "myRestApi", 
  path: "/users",
  options: {
    queryParams: {
      limit: "10",
      offset: "0"
    },
    headers: {
      "Content-Type": "application/json"
    }
  }
});

const result = await response;
const data = await result.body.json(); // Parse JSON response

/**
 * Performs HTTP POST request
 * @param input - Request configuration including API name, path, and body
 * @returns PostOperation promise that resolves to response
 */
function post(input: PostInput): PostOperation;

interface PostInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface PostOperation {
  response: Promise<RestApiResponse>;
  cancel(abortMessage?: string): void;
}

import { post } from "@aws-amplify/api";

// POST request with JSON body
const { response } = post({
  apiName: "myRestApi",
  path: "/users",
  options: {
    body: {
      name: "John Doe",
      email: "john@example.com"
    },
    headers: {
      "Content-Type": "application/json"
    }
  }
});
const result = await response;

// POST with FormData
const formData = new FormData();
formData.append("file", fileBlob);
formData.append("title", "My File");

const { response } = post({
  apiName: "myRestApi",
  path: "/upload",
  options: {
    body: formData
  }
});
const result = await response;

/**
 * Performs HTTP PUT request
 * @param input - Request configuration including API name, path, and body
 * @returns PutOperation promise that resolves to response
 */
function put(input: PutInput): PutOperation;

interface PutInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface PutOperation {
  response: Promise<RestApiResponse>;
  cancel(abortMessage?: string): void;
}

/**
 * Performs HTTP DELETE request
 * @param input - Request configuration including API name and path
 * @returns DeleteOperation promise that resolves to response
 */
function del(input: DeleteInput): DeleteOperation;

interface DeleteInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface DeleteOperation {
  response: Promise<RestApiResponse>;
  cancel(abortMessage?: string): void;
}

/**
 * Performs HTTP PATCH request
 * @param input - Request configuration including API name, path, and body
 * @returns PatchOperation promise that resolves to response
 */
function patch(input: PatchInput): PatchOperation;

interface PatchInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface PatchOperation {
  response: Promise<RestApiResponse>;
  cancel(abortMessage?: string): void;
}

/**
 * Performs HTTP HEAD request
 * @param input - Request configuration including API name and path
 * @returns HeadOperation promise that resolves to response with headers only
 */
function head(input: HeadInput): HeadOperation;

interface HeadInput {
  apiName: string;
  path: string;
  options?: RestApiOptionsBase;
}

interface HeadOperation {
  response: Promise<Omit<RestApiResponse, 'body'>>;
  cancel(abortMessage?: string): void;
}

interface RestApiOptionsBase {
  /**
   * Request headers
   */
  headers?: Record<string, string>;
  
  /**
   * URL query parameters
   */
  queryParams?: Record<string, string>;
  
  /**
   * Request body - can be JSON object, string, or FormData
   */
  body?: DocumentType | FormData;
  
  /**
   * Include credentials in cross-origin requests
   */
  withCredentials?: boolean;
  
  /**
   * Custom retry strategy for failed requests
   */
  retryStrategy?: RetryStrategy;
  
  /**
   * Request timeout in milliseconds
   */
  timeout?: number;
  
  /**
   * Custom user agent details
   */
  userAgentSuffix?: string;
}

type DocumentType = string | Record<string, any> | ArrayBuffer | Blob;

interface RestApiResponse {
  /**
   * Response body with multiple format support
   */
  body: {
    blob(): Promise<Blob>;
    json(): Promise<any>;
    text(): Promise<string>;
  };
  
  /**
   * HTTP status code
   */
  statusCode: number;
  
  /**
   * Response headers
   */
  headers: Record<string, string>;
}

/**
 * Check if an error is from request cancellation
 * @param error - Error to check
 * @returns boolean indicating if error is from cancellation
 */
function isCancelError(error: unknown): boolean;

/**
 * Cancel a REST API request
 * Can be called on any of the operation promises
 */
interface CancellationSupport {
  cancel(message?: string): void;
}

import { get, post, isCancelError } from "@aws-amplify/api";

// Request with cancellation
const { response, cancel } = get({
  apiName: "myRestApi",
  path: "/slow-endpoint"
});

// Cancel after 5 seconds
setTimeout(() => {
  cancel("Request timed out");
}, 5000);

try {
  const result = await response;
} catch (error) {
  if (isCancelError(error)) {
    console.log("Request was cancelled");
  } else {
    console.error("Request failed:", error);
  }
}

interface RetryStrategy {
  /**
   * Maximum number of retry attempts
   */
  maxRetries?: number;
  
  /**
   * Delay between retries in milliseconds
   */
  retryDelayMs?: number;
  
  /**
   * Custom function to determine if request should be retried
   */
  shouldRetry?: (error: Error, attempt: number) => boolean;
  
  /**
   * Custom delay calculation function
   */
  delayFunction?: (attempt: number, baseDelay: number) => number;
}

import { post } from "@aws-amplify/api";

// Custom retry strategy
const { response } = post({
  apiName: "myRestApi",
  path: "/unreliable-endpoint",
  options: {
    body: { data: "important" },
    retryStrategy: {
      maxRetries: 3,
      retryDelayMs: 1000,
      shouldRetry: (error, attempt) => {
        // Only retry on 5xx server errors
        return error.message.includes("5") && attempt < 3;
      }
    }
  }
});
const result = await response;