Skip to main content

Reference: Idempotency Subsystem

The Idempotency subsystem in Framework M ensures that mutating API requests (POST, PUT, PATCH, DELETE) can be safely retried without causing unintended duplicate side-effects (e.g., double billing).

It consists of a backend IdempotencyProtocol, caching adapters, a Litestar middleware, and frontend UI hooks.

Backend Reference​

[!NOTE] The backend Python APIs for Idempotency are automatically generated from source code.

Please refer to the following auto-generated modules for detailed API specifications:

  • framework_m_core.interfaces.idempotency (For the IdempotencyProtocol)
  • framework_m_standard.adapters.cache.idempotency (For Database and Redis adapters)
  • framework_m_standard.adapters.web.middleware.idempotency (For the Litestar Middleware)

Frontend Reference​

useCall Hook​

Location: @framework-m/desk/src/hooks/useCall

A React hook for triggering backend side-effects while automatically generating and managing idempotency keys.

Type Signature:

interface UseCallOptions {
  doctype?: string;
  method?: string;
  path?: string;
  payload?: any;
}

interface UseCallReturn {
  execute: (options: UseCallOptions) => Promise<any>;
  isLoading: boolean;
  data: any | null;
  error: Error | null;
}

Behavior: When execute is called, it generates a UUIDv4 and sets the Idempotency-Key header on the outgoing fetch request. It guarantees that if the frontend library automatically retries the network request (e.g., via React Query or native fetch wrappers), the exact same UUIDv4 is used.