http_api_handler 1.0.1
http_api_handler: ^1.0.1 copied to clipboard
A Flutter package for handling HTTP API requests with ease, including file uploads and downloads.
HTTP API Handler #
A powerful and flexible Flutter package for handling HTTP API requests with built-in logging, error handling, and file operations. Designed to simplify API integration in Flutter applications.
Features ๐ #
- โจ Easy-to-use HTTP methods (GET, POST, PUT, DELETE)
- ๐ File upload support (single and multiple files)
- โฌ๏ธ File download capability
- ๐ Built-in logging system
- โ Comprehensive error handling
- ๐ Authentication token support
- ๐ Query parameters support
- ๐ฏ Custom base URL support
- ๐งช Fully tested
Installation ๐ป #
Add this to your package's pubspec.yaml
file:
dependencies:
http_api_handler: ^1.0.0
Then run:
flutter pub get
Usage ๐ฑ #
Initialize the API Handler #
final api = ApiHandler(
baseURL: 'https://api.example.com', // Your API base URL
authToken: 'your_auth_token', // Optional: JWT or other auth token
enableLogs: true, // Enable/disable logging
additionalHeaders: { // Optional: Additional headers
'Custom-Header': 'Value',
},
);
Basic HTTP Requests #
GET Request
// Simple GET request
try {
final response = await api.get(
endPoint: '/users',
);
print('Users: $response');
} catch (e) {
print('Error: $e');
}
// GET request with query parameters
try {
final response = await api.get(
endPoint: '/users',
queryParameters: {
'page': '1',
'limit': '10',
'sort': 'desc',
},
);
print('Filtered Users: $response');
} catch (e) {
print('Error: $e');
}
POST Request
try {
final response = await api.post(
endPoint: '/users',
body: {
'name': 'John Doe',
'email': 'john@example.com',
'age': 30,
},
);
print('Created User: $response');
} catch (e) {
print('Error: $e');
}
PUT Request
try {
final response = await api.put(
endPoint: '/users/123',
body: {
'name': 'Updated Name',
'email': 'updated@example.com',
},
);
print('Updated User: $response');
} catch (e) {
print('Error: $e');
}
DELETE Request
try {
final response = await api.delete(
endPoint: '/users/123',
);
print('Deleted User: $response');
} catch (e) {
print('Error: $e');
}
File Operations #
Upload Single File
try {
final response = await api.uploadFiles(
endPoint: '/upload',
files: [yourFile], // PlatformFile from file_picker
singleFile: true,
fields: { // Optional additional fields
'type': 'profile',
'userId': '123',
},
onProgress: (sent, total) {
final progress = (sent / total * 100).toStringAsFixed(2);
print('Upload Progress: $progress%');
},
);
print('Upload Response: $response');
} catch (e) {
print('Upload Error: $e');
}
Upload Multiple Files
try {
final response = await api.uploadFiles(
endPoint: '/upload/multiple',
files: yourFiles, // List<PlatformFile> from file_picker
singleFile: false,
fields: {'type': 'gallery'},
onProgress: (sent, total) {
final progress = (sent / total * 100).toStringAsFixed(2);
print('Upload Progress: $progress%');
},
);
print('Multiple Upload Response: $response');
} catch (e) {
print('Upload Error: $e');
}
Download File
try {
final fileBytes = await api.downloadFile(
endPoint: '/download',
body: {'fileId': '123'},
);
// Handle the downloaded file bytes
// Example: Save to file system
await File('downloaded_file.pdf').writeAsBytes(fileBytes);
} catch (e) {
print('Download Error: $e');
}
Error Handling #
The package provides specific exceptions for different scenarios:
try {
final response = await api.get(endPoint: '/protected-resource');
} on AuthenticationException catch (e) {
// Handle 401 Unauthorized
print('Authentication Error: ${e.message}');
// Example: Redirect to login
} on BadRequestException catch (e) {
// Handle 400 Bad Request
print('Bad Request: ${e.message}');
// Example: Show validation errors
} on ServerException catch (e) {
// Handle 500 Server Error
print('Server Error: ${e.message}');
// Example: Show server error message
} on NetworkException catch (e) {
// Handle network/connectivity issues
print('Network Error: ${e.message}');
// Example: Show offline message
} on ApiException catch (e) {
// Handle other API errors
print('API Error: ${e.message} (${e.statusCode})');
// Example: Show generic error message
}
Logging #
The package includes comprehensive logging that can be enabled/disabled:
// Enable logging (default: true)
final api = ApiHandler(
baseURL: 'https://api.example.com',
enableLogs: true,
);
// Logs will include:
// โ Request URL
// โ Request Method
// โ Request Headers
// โ Request Body
// โ Response Status Code
// โ Response Body
// โ Error Details (if any)
Custom Base URL #
You can use a different base URL for specific requests:
final response = await api.post(
endPoint: '/special-endpoint',
body: {'data': 'value'},
customBaseURL: 'https://another-api.com',
);
Error Types ๐จ #
Exception Type | Description | Status Code |
---|---|---|
ApiException | Base exception class | Any |
AuthenticationException | Authentication failed | 401 |
BadRequestException | Invalid request | 400 |
ServerException | Server error | 500 |
NetworkException | Network/connectivity issues | N/A |
Contributing ๐ค #
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push to the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Testing ๐งช #
The package includes comprehensive tests. Run them with:
flutter test
License ๐ #
This project is licensed under the MIT License - see the LICENSE file for details.
Author โ๏ธ #
Anwar Safy
- GitHub: @anwarsafy
- LinkedIn: @anwar-safy
Support โค๏ธ #
If you find this package helpful, please give it a โญ๏ธ on GitHub!
Changelog ๐ #
See CHANGELOG.md for all changes.
Issues and Feedback ๐ญ #
Please file specific issues, bugs, or feature requests in our issue tracker.
FAQ ๐ #
Q: Can I use this package with DIO?
A: Currently, the package uses the http package. DIO support might be added in future versions.
Q: Is this package null-safe?
A: Yes, this package is null-safe and requires Dart SDK 2.12.0 or later.
Q: Does it support file upload progress?
A: Yes, file upload progress can be monitored using the onProgress callback in file upload methods.
Q: Can I use custom error handling?
A: Yes, you can catch the base ApiException and implement your own error handling logic.
Q: Is it compatible with Flutter Web?
A: Yes, this package is fully compatible with Flutter Web and all other Flutter platforms.
Q: Can I add custom headers?
A: Yes, you can add custom headers through the additionalHeaders parameter when initializing the ApiHandler.
Q: How do I handle refresh tokens?
A: You can implement a custom interceptor by extending the ApiHandler class and overriding the necessary methods.