SmoothAPI

Protect Your Application from Third-Party API Failures

A failing third-party API can bring down your entire application, leading to cascading service failures, degraded user experience, and lost revenue. SmoothAPI stops these crashes from breaking your app by wrapping your HTTP calls with industry-standard resilience patterns.

SmoothAPI catches network errors instantly, spaces out retries so recovering servers can breathe, and serves safe backup data the millisecond a service goes completely dead.

Core Features

• Exponential Backoff & Full Jitter: Retries transient failures with exponentially increasing delays. It generates randomized "jitter" boundaries to prevent client requests from hammering recovering endpoints in sync (the "thundering herd" problem).
• Per-Domain Circuit Breaker: Tracks API health in isolated state machines. If a specific domain reaches your failure threshold, the circuit trips to OPEN, immediately blocking further connections and returning fallback data. This prevents resource starvation and cascading failures.
• Graceful Client-Error Fallbacks: Support for fallbackOnNonRetryable. Safely intercept non-retryable client-side HTTP codes (like 404, 403, 400) and return custom data, show browser alerts, or fire custom notification callbacks instead of throwing app-breaking crashes.

Dual-Language Support

SmoothAPI is implemented natively in both TypeScript and Python to ensure high performance and seamless support for different environments.

• TypeScript: A dual-environment fetch wrapper supporting Edge, Serverless, and Node.js with built-in type inference.
• Python: An elegant function decorator supporting both sync and async functions, integrating smoothly with requests and httpx.

How to Get Started

Initialize a custom resilient fetch instance using createResilientFetch in TypeScript or the provided decorator in Python. Configure your resilience parameters such as backoff delays, retry limits, and circuit breaker thresholds.

1. Initialize the library with your desired configuration (e.g., base delay, max retries).
2. Configure the circuit breaker threshold and cooldown period.
3. Define a fallback mechanism to return safe backup data when a service is down.
4. Use it as a drop-in replacement for native fetch calls or decorators.

Configuration Options

Customize the behavior of SmoothAPI using these properties:

• backoff.baseDelay: Initial wait time before the first retry (ms in TS, seconds in Python).
• backoff.maxRetries: Maximum number of attempts to resolve the request.
• circuitBreaker.failureThreshold: Consecutive failures needed to trip the circuit to OPEN.
• circuitBreaker.cooldownMs: Time to wait (in ms) before entering HALF_OPEN probe state.
• fallback: Object returned immediately on an OPEN circuit or client error.
• fallbackOnNonRetryable: If true, returns fallbacks or mock responses on non-retryable client codes (e.g., 404, 401).
• onNonRetryableError: Custom callback fired when a client-error occurs. Disables default browser alerts.