Introduction

A failing third-party API can bring down your entire application, leading to cascading service failures, degraded user experience, and lost revenue. How do you protect your systems and keep them resilient, even when downstream dependencies are completely unresponsive or failing?

Enter SmoothAPI. SmoothAPI stops third-party API crashes from breaking your app. It wraps your HTTP calls with industry-standard resilience patterns, catches network errors instantly, spaces out retries so recovering servers can breathe, and serves safe backup data the millisecond a service goes completely dead.

TypeScript Native

Dual-environment fetch wrapper supporting Edge, Serverless, and Node.js with built-in type inference.

Python Native

Elegant function decorator supporting both sync and async functions, integrating smoothly with requests and httpx.

Installation

TypeScript/JavaScript (NPM):

npm install @codingaryan/smoothapi

Python (PyPI):

pip install smoothapi-py

Quickstart Guide

Create a custom resilient fetch instance and use it as a drop-in replacement for native `fetch`:

import { createResilientFetch } from '@codingaryan/smoothapi';

const fetchWithRetry = createResilientFetch({
  backoff: {
    baseDelay: 100,      // ms
    maxRetries: 3        // retry 3 times
  },
  circuitBreaker: {
    failureThreshold: 3, // trip OPEN after 3 consecutive errors
    cooldownMs: 10000    // stay OPEN for 10 seconds
  },
  fallback: { status: "degraded", data: [] }
});

// Use it just like normal fetch!
const response = await fetchWithRetry('https://api.example.com/unstable');

Core Features

Exponential Backoff & Full Jitter

Retries transient failures with exponentially increasing delays. 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` / `fallback_on_non_retryable`. 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.

Interactive Simulator

Test how the circuit breaker and fallback mechanisms work in real-time. Toggle network failures, dispatch requests, and monitor the circuit status well logs:

COMING SOON

Interactive API Sandbox

We are building a comprehensive real-time dashboard simulator. You will be able to inject customizable latency, simulate network timeouts, trigger random HTTP exceptions, and watch the circuit breaker dynamically transition states live.

Simulated Telemetry

[10:42:01] INFO Initializing state machine...

[10:42:02] INFO Target endpoint: api.smooth.dev/v1/chaos

[10:42:03] WARN Failure rate set to 80%. Ready to probe.

Configuration Options

Customize the behavior of `SmoothAPI` using the following properties when initializing:

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