QuickApi #

QuickApi is a powerful and easy-to-use Flutter package for seamless API integrations with advanced features like automatic retry, caching, interceptors, and network connectivity checks.

✨ Features #

🚀 Complete HTTP Methods - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and multipart uploads
🔄 Smart Retry Mechanism - Configurable retries with exponential backoff support
💾 Advanced Caching - Response caching with size limits and manual cache control
🌐 Network Connectivity Checks - Automatic network availability validation
🔧 Powerful Interceptor System - Request/response/error interceptors with abort control
📝 Structured Logging - Level-based logging (INFO, ERROR, DEBUG, WARN)
⚡ Fluent Builder Pattern - Easy configuration with method chaining
🛡️ Comprehensive Error Handling - Sealed error classes with endpoint context
⏱️ Granular Timeout Control - Separate connect, read, and write timeouts
🎯 Query Parameters Support - Built-in query parameter handling
🚫 Request Cancellation - CancelToken for canceling in-flight requests
📊 Upload Progress - Progress callbacks for file uploads
🎯 Customizable Headers - Default and per-request header management

📦 Installation #

Add the following dependency to your pubspec.yaml:

dependencies:
  quickapi: ^2.0.0

Then run:

flutter pub get

🚀 Quick Start #

Basic Usage #

import 'package:quickapi/quickapi.dart';

// Simple initialization
final api = QuickApi(
  baseUrl: 'https://api.example.com',
  logger: (level, message) => print('[$level] $message'),
);

// Make requests
final response = await api.get('/users');
final newUser = await api.post('/users', {
  'name': 'John Doe',
  'email': 'john@example.com'
});

Advanced Configuration with Builder Pattern #

final api = QuickApi.builder()
  .baseUrl('https://api.example.com')
  .timeout(Duration(seconds: 15))
  .retry(3, delay: Duration(seconds: 1), useExponentialBackoff: true)
  .cache(Duration(minutes: 5), maxSize: 100)
  .addInterceptor(LoggingInterceptor())
  .logger((level, message) => print('[API $level] $message'))
  .build();

📚 Usage Examples #

1. Import Dependencies #

import 'package:quickapi/quickapi.dart';
import 'package:http/http.dart' as http;

2. Initialize QuickApi #

Simple Initialization

class _ApiTestPageState extends State<ApiTestPage> {
  late QuickApi _api;

  @override
  void initState() {
    super.initState();
    _api = QuickApi(
      baseUrl: 'https://jsonplaceholder.typicode.com',
      logger: (message) => print('[QuickApi] $message'),
    );
  }
}

Advanced Configuration with Builder

_api = QuickApi.builder()
  .baseUrl('https://jsonplaceholder.typicode.com')
  .timeout(Duration(seconds: 15))
  .retry(3, delay: Duration(seconds: 1))
  .addInterceptor(LoggingInterceptor())
  .logger((message) => print('[QuickApi] $message'))
  .build();

3. Make API Calls #

GET Request

void _testGet() async {
  try {
    // With query parameters
    final result = await _api.get('/posts/1',
      queryParameters: {'include': 'comments'}
    );
    print('GET Response: $result');
  } catch (e) {
    print('Error: $e');
  }
}

POST Request

void _testPost() async {
  final params = {
    'title': 'New Post',
    'body': 'This is a new post.',
    'userId': 1,
  };

  try {
    final result = await _api.post('/posts', params);
    print('POST Response: $result');
  } catch (e) {
    print('Error: $e');
  }
}

PUT Request

void _testPut() async {
  try {
    final result = await _api.put('/posts/1', {
      'title': 'Updated Post',
      'body': 'This is an updated post.',
      'userId': 1,
    });
    print('PUT Response: $result');
  } catch (e) {
    print('Error: $e');
  }
}

PATCH Request

void _testPatch() async {
  try {
    final result = await _api.patch('/posts/1', {
      'title': 'Partially Updated Post',
    });
    print('PATCH Response: $result');
  } catch (e) {
    print('Error: $e');
  }
}

DELETE Request

void _testDelete() async {
  try {
    final result = await _api.delete('/posts/1');
    print('DELETE Response: $result');
  } catch (e) {
    print('Error: $e');
  }
}

File Upload (Multipart POST)

void _testFileUpload() async {
  try {
    final file = await _pickFile();
    if (file != null) {
      final result = await _api.postMultipart('/upload', {
        'description': 'Test File Upload'
      }, [
        http.MultipartFile.fromBytes('file', await file.readAsBytes(),
            filename: 'file.jpg')
      ], onProgress: (sent, total) {
        print('Upload progress: ${(sent / total * 100).toStringAsFixed(1)}%');
      });
      print('Upload Response: $result');
    }
  } catch (e) {
    print('Error: $e');
  }
}

🔧 Configuration Options #

QuickApi Constructor Parameters #

Parameter	Type	Default	Description
`baseUrl`	`String`	Required	Base URL for all API requests
`defaultHeaders`	`Map<String, String>?`	`null`	Default headers for all requests
`timeoutDuration`	`Duration`	`30 seconds`	Request timeout duration
`retryCount`	`int`	`3`	Number of retry attempts
`retryDelay`	`Duration`	`2 seconds`	Delay between retry attempts
`cacheDuration`	`Duration`	`5 minutes`	Cache expiration duration
`interceptors`	`List<QuickApiInterceptor>`	`[]`	List of interceptors
`logger`	`Function(String, String)?`	`null`	Logging function (level, message)
`useExponentialBackoff`	`bool`	`true`	Use exponential backoff for retries
`maxBackoffDuration`	`Duration`	`60 seconds`	Maximum backoff duration
`maxCacheSize`	`int?`	`null`	Maximum number of cached responses
`connectTimeout`	`Duration?`	`null`	Connection timeout
`readTimeout`	`Duration?`	`null`	Read timeout
`writeTimeout`	`Duration?`	`null`	Write timeout
`httpClient`	`http.Client?`	`null`	Custom HTTP client

Builder Pattern Methods #

Method	Description
`.baseUrl(String)`	Set the base URL
`.defaultHeaders(Map)`	Set default headers
`.timeout(Duration)`	Set timeout duration
`.retry(int, {Duration? delay})`	Set retry count and delay
`.addInterceptor(Interceptor)`	Add an interceptor
`.logger(Function)`	Set logging function (level, message)
`.cache(Duration, {int? maxSize})`	Configure cache duration and size
`.connectTimeout(Duration)`	Set connection timeout
`.readTimeout(Duration)`	Set read timeout
`.writeTimeout(Duration)`	Set write timeout
`.httpClient(http.Client)`	Set custom HTTP client

🎯 Interceptors #

Built-in Logging Interceptor #

// Add logging to all requests
final api = QuickApi.builder()
  .baseUrl('https://api.example.com')
  .addInterceptor(LoggingInterceptor())
  .build();

Custom Interceptor #

class AuthInterceptor implements QuickApiInterceptor {
  @override
  Future<void> onRequest(RequestContext context) async {
    // Add auth token to headers
    context.data['headers'] = {'Authorization': 'Bearer $token'};
  }

  @override
  Future<void> onResponse(ResponseContext context) async {
    // Handle response (e.g., refresh token if 401)
    if (context.data is Map && context.data['statusCode'] == 401) {
      // Handle unauthorized
    }
  }
}

// Use custom interceptor
final api = QuickApi.builder()
  .baseUrl('https://api.example.com')
  .addInterceptor(AuthInterceptor())
  .build();

🚨 Error Handling #

QuickApi provides specific error types for different scenarios:

Error Types #

TimeoutError - Request timeout
NetworkError - Network connectivity issues
AuthenticationError - 401 Unauthorized responses
ValidationError - 422 Validation failures
RateLimitError - 429 Too Many Requests
ClientError - 4xx client errors
ServerError - 5xx server errors
UnknownError - Other status codes

Error Handling Example #

try {
  final response = await api.get('/users');
} on AuthenticationError catch (e) {
  print('Auth failed: ${e.message}');
  // Redirect to login
} on ValidationError catch (e) {
  print('Validation failed: ${e.errors}');
  // Show validation errors
} on NetworkError catch (e) {
  print('Network issue: ${e.message}');
  // Show offline message
} catch (e) {
  print('Unexpected error: $e');
}

💾 Caching #

QuickApi automatically caches successful GET responses:

// Enable caching (default: true)
final response1 = await api.get('/users'); // Network request
final response2 = await api.get('/users'); // Cached response

// Disable caching for specific requests
final response3 = await api.get('/users', useCache: false);

// Clear all cache
api.clearCache();

// Check cache size
print('Cache size: ${api.cacheSize}');

🔄 Retry Mechanism #

Automatic retry for failed requests:

final api = QuickApi.builder()
  .baseUrl('https://api.example.com')
  .retry(3, delay: Duration(seconds: 1)) // 3 attempts, 1 second delay
  .build();

// If a request fails, it will automatically retry up to 3 times
// With exponential backoff enabled by default
final response = await api.get('/users');

🌐 Network Connectivity #

QuickApi automatically checks network connectivity before making requests:

// No need to manually check - QuickApi handles this automatically
final response = await api.get('/users');
// If no internet, throws NetworkError immediately

// You can also cancel requests
final cancelToken = CancelToken();
api.get('/users', cancelToken: cancelToken);
// Later, cancel the request
cancelToken.cancel();

🧪 Testing #

Run the test suite:

flutter test

The package includes comprehensive tests for all functionality including:

Initialization and configuration
Builder pattern
Error handling
Interceptor system
Caching behavior

📝 Logging #

Enable logging to monitor API requests:

final api = QuickApi(
  baseUrl: 'https://api.example.com',
  logger: (message) => print('[API] $message'),
);

// Or use the built-in logging interceptor
final api = QuickApi.builder()
  .baseUrl('https://api.example.com')
  .addInterceptor(LoggingInterceptor())
  .build();

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

quickapi 2.0.0 quickapi: ^2.0.0 copied to clipboard

Metadata