or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

graphql-client.mdindex.mdrealtime-events.mdrest-api.mdserver-apis.md
tile.json

tessl/npm-aws-amplify--api

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-amplify/api@6.3.x

To install, run

npx @tessl/cli install tessl/npm-aws-amplify--api@6.3.0

index.mddocs/

AWS Amplify API

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