tessl/npm-aws-amplify--api

A unified API layer for AWS Amplify that combines GraphQL and REST API functionality

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

REST API Methods

Name: tessl/npm-aws-amplify--api
Author: tessl

Complete set of HTTP methods for making REST API requests with full configuration support and request cancellation.

Capabilities

HTTP GET

Performs HTTP GET requests to retrieve data from REST APIs.

/**
 * 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;
}

Usage Examples:

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

HTTP POST

Performs HTTP POST requests to create new resources.

/**
 * 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;
}

Usage Examples:

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;

HTTP PUT

Performs HTTP PUT requests to update existing resources.

/**
 * 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;
}

HTTP DELETE

Performs HTTP DELETE requests to remove resources.

/**
 * 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;
}

HTTP PATCH

Performs HTTP PATCH requests to partially update resources.

/**
 * 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;
}

HTTP HEAD

Performs HTTP HEAD requests to retrieve headers without response body.

/**
 * 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;
}

Request Configuration

Common configuration options for all REST API methods.

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;

Response Interface

Structure of REST API responses.

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>;
}

Request Cancellation

Utilities for canceling REST API requests.

/**
 * 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;
}

Usage Examples:

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);
  }
}

Retry Strategy

Configuration for automatic request retries on failure.

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;
}

Usage Examples:

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;