baaba_api_handler #

A Flutter package for HTTP API communication and response caching. Wraps Dio with structured error handling, automatic token refresh, network retry, and local cache management.

Table of Contents #

• Installation
• Features
  • Network API Handler
    • Configuration (Token Auth)
    • GET
    • POST
    • PUT
    • PATCH
    • DELETE
    • Cancel Request
  • API Cache Management
    • Get Cache
    • Set Cache
    • Clear Cache
    • Cache Exists
    • Clear All Cache

Installation #

1. Add Dependency

Add to your pubspec.yaml:

dependencies:
  baaba_api_handler: ^1.1.0

2. Install Packages

flutter pub get

3. Import the Library

import 'package:baaba_api_handler/ts_api_handler.dart';

Response, CancelToken (Dio), and APICacheDBModel are re-exported from this single import — no need to add dio or api_cache_manager as direct dependencies.

Features #

1. Network API Handler #

Provides typed HTTP methods with built-in network checks, automatic token refresh, network retry, and structured error responses.

Create a singleton instance:

final apiServices = ApiServices.instance();

Request Parameters

All HTTP methods share these parameters:

All methods return Either<Failure, Response>:

response.fold(
  (failure) => print('Error ${failure.message}'),
  (success) => print(success.data),
);

1.1 Configuration (Token Auth)

Call ApiServices.configure() once at app startup to enable automatic token injection and refresh on 401 responses:

ApiServices.configure(
  getToken: () async => await storage.read(key: 'access_token'),
  onTokenRefresh: () async {
    // Perform your refresh logic here.
    // Return true if the token was refreshed successfully.
    return await authRepository.refresh();
  },
  onRefreshFailed: () {
    // Called when refresh fails — typically trigger logout.
    authController.logout();
  },
);

If you do not need token auth, skip this and call ApiServices.instance() directly.

Custom Headers with headerBuilder

By default the token is injected as Authorization: Bearer <token>. Use headerBuilder when you need a different scheme or additional headers:

// Different auth scheme
ApiServices.configure(
  getToken: () async => await storage.read(key: 'token'),
  onTokenRefresh: () async => await authRepo.refresh(),
  headerBuilder: (token) => {
    'Authorization': 'Token $token',
  },
);

// Multiple fields — token + tenant ID + API key
ApiServices.configure(
  getToken: () async => await storage.read(key: 'token'),
  onTokenRefresh: () async => await authRepo.refresh(),
  headerBuilder: (token) => {
    'Authorization': 'Bearer $token',
    'X-Tenant-Id': 'my-org',
    'X-Api-Key': 'abc123',
  },
);

The returned map is merged into every request's headers, including automatic retries after a token refresh.

Bypass Connectivity Check

On internal or staging networks where external connectivity probes always fail (e.g. behind a proxy or firewall), pass bypassConnectivityCheck: true to skip the pre-flight check:

// Staging entry point — internal network with proxy
ApiServices.configure(
  getToken: () async => await storage.read(key: 'access_token'),
  onTokenRefresh: () async => await authRepository.refresh(),
  onRefreshFailed: () => authController.logout(),
  bypassConnectivityCheck: true,
);

If you don't need token auth but still need to disable the connectivity check, use setConnectivityCheck:

// Before configureDependencies() in your staging entry point
ApiServices.setConnectivityCheck(enabled: false);

1.2 GET

final response = await apiServices.get(endpoint: 'https://api.example.com/users');

1.3 POST

final response = await apiServices.post(
  endpoint: 'https://api.example.com/users',
  data: {'name': 'Baaba'},
);

1.4 PUT

final response = await apiServices.put(
  endpoint: 'https://api.example.com/users/1',
  data: {'name': 'Baaba Updated'},
);

1.5 PATCH

final response = await apiServices.patch(
  endpoint: 'https://api.example.com/users/1',
  data: {'name': 'Baaba Patched'},
);

1.6 DELETE

final response = await apiServices.delete(endpoint: 'https://api.example.com/users/1');

1.7 Cancel Request

Cancel all in-flight requests at once:

apiServices.cancelRequest();

// With an optional reason:
apiServices.cancelRequest(cancellationReason: 'User navigated away');

To cancel a specific request, pass a CancelToken when making the call:

final token = CancelToken();
final response = await apiServices.get(endpoint: url, cancelToken: token);

// Later:
token.cancel('Cancelled by user');

2. API Cache Management #

Caches API responses in a local SQLite database to reduce unnecessary network calls and support offline-first behaviour.

final apiCacheHelper = ApiCacheHelper.instance;

2.1 Get Cache

final cached = await apiCacheHelper.getCacheData(url);

2.2 Set Cache

final stored = await apiCacheHelper.setCacheData(url, data);

2.3 Clear Cache

final cleared = await apiCacheHelper.clearCache(url);

2.4 Cache Exists

final exists = await apiCacheHelper.isCacheExist(url);

2.5 Clear All Cache

await apiCacheHelper.clearAllCache();