import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/en/functional-basic/Classes/Api - Request Management (Static)'/>

# Api Class

The `Api` class is a **Primary Class (Static)** and serves as the main entry point for managing HTTP requests. It is a static wrapper around a globally managed `ApiInstance`, providing a clean, singleton-based interface for standard network operations.

## Key Features

- **Static Interface** — perform standard HTTP operations (`GET`, `POST`, etc.) without manual instantiation.
- **Global Lifecycle Hooks** — configure request preparation and analysis once for the entire application.
- **SSR Isolation** — utilizes `ServerStorage` to manage individual instance isolation during server-side rendering.
- **Simplified Setup** — provides a unified `setConfig` method to apply multiple configuration layers at once.

## Methods

### Action

Methods for performing physical network requests.

- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Core executor; accepts a path string or configuration object.
- `get<T>(request: ApiFetch): Promise<T>` — Sends a GET request.
- `post<T>(request: ApiFetch): Promise<T>` — Sends a POST request.
- `put<T>(request: ApiFetch): Promise<T>` — Sends a PUT request.
- `patch<T>(request: ApiFetch): Promise<T>` — Sends a PATCH request.
- `delete<T>(request: ApiFetch): Promise<T>` — Sends a DELETE request.

### Check

- `isLocalhost(): boolean` — Checks if the current environment is a local development server.

### Configuration

- `setUrl(url: string): void` — Changes the base API URL.
- `setHeaders(headers: Record<string, string>): void` — Sets default request headers.
- `setRequestDefault(request: Record<string, any>): void` — Sets default request body data.
- `setPreparation(callback): void` — Registers a hook to run before every enabled request.
- `setEnd(callback): void` — Registers a hook to run after every enabled response.
- `setTimeout(timeout: number): void` — Changes the global request timeout.
- `setOrigin(origin: string): void` — Changes the origin (protocol and domain) for the base URL.
- `setConfig(config?: ApiConfig): void` — Applies a complete configuration object.

### Auxiliary

- `getStatus(): ApiStatus` — Accesses the status manager for the last request.
- `getResponse(): ApiResponse` — Accesses the response/emulation manager.
- `getHydration(): ApiHydration` — Accesses the hydration manager.
- `getHydrationScript(): string` — Returns the script block for SSR-to-client hydration.
- `getOrigin(): string` — Returns the base origin URL combined with the API path.
- `getUrl(path: string, api?: boolean): string` — Returns the fully resolved URL with `{locale}`, `{country}`, `{language}` placeholder substitution.
- `getBody(request, method?): string | FormData | undefined` — Prepares the request body.
- `getBodyForGet(request, path?, method?): string` — Prepares the query string.
- `getItem(): ApiInstance` — Returns the underlying `ApiInstance` object.

## Types

### ApiConfig

- `urlRoot: string` — the base URL for the API.
- `origin: string` — protocol and domain for the base URL.
- `headers: Record<string, string>` — default request headers.
- `requestDefault: Record<string, any>` — default request data.
- `preparation: (apiFetch: ApiFetch) => Promise<void>` — entry hook.
- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — exit hook.
- `timeout: number` — global timeout in milliseconds.

## Proxy Architecture

The `Api` class operates as a **Static Proxy**. All method calls are redirected to an internal `ApiInstance`.

### Instance Management

The internal manager is stored in `ServerStorage` using a unique key (`__dxt_api_instance__`). This architecture solves two major problems:

1.  **Thread Safety in SSR**: During server-side rendering, `ServerStorage` ensures that each incoming request has its own isolated API configuration and state, preventing data leaks between users.
2.  **Singleton Simplicity on Client**: On the client side, it behaves as a true singleton, allowing you to configure the API in your entry point and use it anywhere without passing instances.

### Delegation

While `Api` is the preferred interface for standard application logic, the core logic (retries, hydration logic, jitter) resides within `ApiInstance`. For advanced scenarios involving multiple base URLs or different header sets simultaneously, you may instantiate `ApiInstance` directly.
