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

AWS Amplify API

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

AWS Amplify API provides a unified API layer that combines GraphQL and REST API functionality. It serves as a higher-level abstraction over the @aws-amplify/api-graphql and @aws-amplify/api-rest packages, providing a single entry point for developers to interact with both GraphQL and REST APIs in AWS Amplify applications.

Package Information

Package Name: @aws-amplify/api
Package Type: npm
Language: TypeScript
Installation: Part of AWS Amplify - intended for internal use only. Install via aws-amplify package.

Core Imports

import { generateClient, get, post, put, del, patch, head } from "@aws-amplify/api";

For server-side usage:

import { generateClient, get, post, put, del, patch, head } from "@aws-amplify/api/server";

For internal/advanced usage:

import { InternalAPI, generateClientWithAmplifyInstance } from "@aws-amplify/api/internals";

Basic Usage

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

// Create a GraphQL client for models
const client = generateClient<Schema>();

// Query data using models
const { data: todos } = await client.models.Todo.list();

// Create new data
const { data: newTodo } = await client.models.Todo.create({
  content: "Learn AWS Amplify",
  completed: false,
});

// Make REST API calls
const { body } = await post({
  apiName: "myRestApi",
  path: "/items",
  options: {
    body: { name: "New Item", description: "Item description" },
  },
});

Architecture

AWS Amplify API is built around several key components:

Unified Interface: Single package that exports both GraphQL and REST functionality
GraphQL Client Generation: Type-safe client generation with model support via generateClient
REST API Methods: Complete HTTP method support (GET, POST, PUT, DELETE, PATCH, HEAD)
Server-Side Rendering: SSR-compatible APIs for Next.js and other frameworks
Real-time Support: WebSocket subscriptions and connection state management
Error Handling: Comprehensive error types and cancellation support
Multi-Environment: Support for browser, React Native, and Node.js environments

Capabilities

GraphQL Client Generation

Core GraphQL functionality for creating type-safe clients that work with Amplify data models or raw GraphQL operations.

function generateClient<T, Options>(options?: Options): V6Client<T, Options>;

type V6Client<T, Options> = {
  graphql: GraphQLMethod<Options>;
  cancel(promise: Promise<any>, message?: string): boolean;
  isCancelError(error: any): boolean;
} & ClientExtensions<T>;

GraphQL Client

REST API Methods

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

function get(input: GetInput): GetOperation;
function post(input: PostInput): PostOperation;
function put(input: PutInput): PutOperation;
function del(input: DeleteInput): DeleteOperation;
function patch(input: PatchInput): PatchOperation;
function head(input: HeadInput): HeadOperation;
function isCancelError(error: unknown): boolean;

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

interface RestApiOptionsBase {
  headers?: Record<string, string>;
  queryParams?: Record<string, string>;
  body?: DocumentType | FormData;
  withCredentials?: boolean;
  retryStrategy?: RetryStrategy;
}

REST API Methods

Real-time and Events

Event system for managing real-time functionality including WebSocket connections and subscription lifecycle.

const events: EventsChannel;
const CONNECTION_STATE_CHANGE: string;

interface EventsChannel {
  subscribe(observer: Observer, options?: EventsOptions): Subscription;
  publish(event: Event, options?: EventsOptions): Promise<any>;
  close(): void;
}

enum ConnectionState {
  Connected = "Connected",
  ConnectedPendingNetwork = "ConnectedPendingNetwork",
  ConnectionDisrupted = "ConnectionDisrupted",
  ConnectionDisruptedPendingNetwork = "ConnectionDisruptedPendingNetwork",
  Connecting = "Connecting",
  ConnectedPendingDisconnect = "ConnectedPendingDisconnect",
  Disconnected = "Disconnected",
  ConnectedPendingKeepAlive = "ConnectedPendingKeepAlive"
}

Real-time and Events

Server-Side APIs

Server-side compatible versions of GraphQL and REST APIs for use in SSR environments like Next.js.

// Server-side GraphQL client generation
function generateClient(): ServerGraphQLClient;

// Server-side REST methods
function get(input: GetInput): GetOperation;
function post(input: PostInput): PostOperation;
function put(input: PutInput): PutOperation;
function del(input: DeleteInput): DeleteOperation;
function patch(input: PatchInput): PatchOperation;
function head(input: HeadInput): HeadOperation;

Server-Side APIs

Internal APIs

Advanced internal APIs for framework integration and custom implementations.

// Internal GraphQL client generation with custom Amplify instance
function generateClientWithAmplifyInstance(
  amplifyInstance: AmplifyInstance
): V6Client;

// Internal API class for DataStore integration (deprecated)
class InternalAPIClass {
  graphql(options: GraphQLOptions, additionalHeaders?: CustomHeaders): Promise<GraphQLResult<any>>;
  getGraphqlOperationType(operation: GraphQLOperation): OperationTypeNode;
}

// Internal REST API methods
function post(
  amplify: AmplifyClassV6,
  options: InternalPostInput
): Promise<RestApiResponse>;

function cancel(promise: Promise<RestApiResponse>, message?: string): boolean;
function updateRequestToBeCancellable(promise: Promise<any>, controller: AbortController): void;

// Server-side SSR client types  
type V6ClientSSRCookies<T, Options = DefaultCommonClientOptions>;
type V6ClientSSRRequest<T, Options = DefaultCommonClientOptions>;

For advanced usage and framework integration - typically not needed for standard applications.

Types

// Core client type with generic support
type Client<T extends Record<any, any> = never> = V6Client<T>;

// GraphQL operation types
type GraphQLQuery<T> = string & { __brand: "GraphQLQuery"; __type: T };
type GraphQLSubscription<T> = string & { __brand: "GraphQLSubscription"; __type: T };
type SelectionSet = Record<string, any>;

// GraphQL result types
interface GraphQLResult<T> {
  data?: T;
  errors?: GraphQLError[];
  extensions?: Record<string, any>;
}

type GraphQLReturnType<T> = T extends { [K in keyof T]: any } 
  ? { [K in keyof T]?: GraphQLReturnType<T[K]> }
  : T;

// Authentication error types
enum GraphQLAuthError {
  NO_API_KEY = "NO_API_KEY",
  NO_CURRENT_USER = "NO_CURRENT_USER", 
  NO_CREDENTIALS = "NO_CREDENTIALS",
  NO_FEDERATED_JWT = "NO_FEDERATED_JWT",
  NO_AUTH_TOKEN = "NO_AUTH_TOKEN"
}

// Base API error class
class ApiError extends Error {
  name: string;
  message: string;
  cause?: Error;
}