cyber_req

A flexible and robust API client for any backend, designed to streamline your Flutter application's network interactions. It offers dynamic header management, secure bearer token handling with flutter_secure_storage, and comprehensive callback mechanisms for success, failure, and unauthorized access.

Features

  • Robust JSON Body Handling: Ensures correct JSON encoding for complex data structures (including arrays of objects) in POST and PUT requests, preventing server-side validation issues.
  • Dynamic Headers: Effortlessly add or override HTTP headers for individual requests, or set global default headers for consistent API communication.
  • Secure Bearer Token Management: Seamlessly integrate bearer tokens into your requests, with built-in support for fetching and storing tokens securely using flutter_secure_storage.
  • Backend Agnostic: Crafted with common API patterns in mind, ensuring smooth handling of JSON responses and efficient error propagation across various backend types.
  • Granular Callbacks: Utilize onSuccess, onFailure, onUnauthorized, and onFinally callbacks to gain fine-grained control over API responses and error handling logic.
  • Custom Exception Handling: Benefit from dedicated ApiException and UnauthorizedException classes for robust and predictable error management.
  • Comprehensive HTTP Method Support: Perform POST, GET, PUT, and DELETE requests with ease.
  • Intelligent Network Error Handling: Automatically catches and reports common network issues such as lack of internet connectivity or invalid response formats.
  • Automatic Request/Response Logging: Optionally log comprehensive request details (URL, method, headers, payload, query parameters) and full response details (URL, status code, body) directly to the console for easy debugging using dart:developer's log function. This is controlled by the autoLogResponse parameter.

Installation

Add cyber_req to your pubspec.yaml file:

dependencies:
  cyber_req: ^2.0.12 # Use the latest version

After adding the dependencies, run flutter pub get in your terminal to fetch the packages.

Quick Start

To see cyber_req in action with various use cases, including basic GET, GET with bearer token (simulating unauthorized), and POST requests with callbacks, refer to the example/main.dart file in the project's example directory.

To run the example:

  1. Navigate to the example directory: 
    cd example
  2. Get the dependencies: 
    flutter pub get
  3. Run the example application: 
    flutter run

This example demonstrates how to use ApiService with onSuccess, onFailure, bearerToken, and onUnauthorized handlers.

API Reference (Brief)

  • ApiService({required String baseUrl, String? bearerToken, http.Client? httpClient, UnauthorizedHandler? onUnauthorized, Map<String, String>? defaultHeaders, bool autoLogResponse = true, Duration timeout = const Duration(seconds: 30)}): Constructor for the API service.
  • Future<Map<String, dynamic>> post(String endpoint, {Map<String, dynamic>? data, Map<String, String>? extraHeaders, String? bearerToken, bool useStorageToken, SuccessCallback? onSuccess, FailureCallback? onFailure, FinallyCallback? onFinally, List<int>? allowedStatusCodes, Duration? timeout}): Sends a POST request.
  • Future<Map<String, dynamic>> get(String endpoint, {Map<String, dynamic>? queryParams, Map<String, String>? extraHeaders, String? bearerToken, bool useStorageToken, SuccessCallback? onSuccess, FailureCallback? onFailure, FinallyCallback? onFinally, List<int>? allowedStatusCodes, Duration? timeout}): Sends a GET request.
  • Future<Map<String, dynamic>> put(String endpoint, {Map<String, dynamic>? data, Map<String, String>? extraHeaders, String? bearerToken, bool useStorageToken, SuccessCallback? onSuccess, FailureCallback? onFailure, FinallyCallback? onFinally, List<int>? allowedStatusCodes, Duration? timeout}): Sends a PUT request.
  • Future<Map<String, dynamic>> delete(String endpoint, {Map<String, String>? extraHeaders, String? bearerToken, bool useStorageToken, SuccessCallback? onSuccess, FailureCallback? onFailure, FinallyCallback? onFinally, List<int>? allowedStatusCodes, Duration? timeout}): Sends a DELETE request.
  • Future<Map<String, dynamic>> postMultipart(String endpoint, {required List<MultipartFile> files, Map<String, String>? fields, Map<String, String>? extraHeaders, String? bearerToken, bool useStorageToken, SuccessCallback? onSuccess, FailureCallback? onFailure, FinallyCallback? onFinally, List<int>? allowedStatusCodes, Duration? timeout}): Sends a multipart POST request with files and optional fields.
  • MultipartFile({required String field, required File file, String? filename}): Constructor for defining a file to be uploaded in a multipart request.
  • void dispose(): Closes the internal HTTP client.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.

License

This project is licensed under the MIT License.

Support and Donations

If you find this package useful and would like to support its continued development, consider a donation!

WhatsApp: Chat with me on WhatsApp

Email: eminibest@gmail.com

cyber_req is maintained by cyberwizard-dev.

Libraries

cyber_req
A flexible Flutter/Dart API client for backends, featuring dynamic headers, secure bearer token management, multipart file uploads, configurable timeouts, and comprehensive callbacks for success, failure, and unauthorized handling.