api_network_kit 1.0.2

A scalable Flutter package featuring a reusable API client (api_kit) for robust HTTP handling using Dio.

network_clients

A scalable Flutter application built with Clean Architecture, featuring a reusable custom package api_kit for robust API handling using Dio. This project demonstrates best practices for organizing large Flutter apps, with a focus on separation of concerns, testability, and maintainability.

---

Table of Contents

• Features
• Getting Started
• Usage
• Clean Architecture Overview
• How to Use api_kit in Your Project
• Testing
• Project Structure
• FAQ / Troubleshooting
• Contributing
• License

---

Features

• Clean Architecture: Feature-first structure with clear separation between presentation, domain, and data layers.
• Reusable API Kit: Custom package for HTTP requests using Dio, with comprehensive features:
  • Logging, token management, generic response parsing
  • Automatic retry mechanisms with exponential backoff
  • Connectivity checking before requests
  • Response caching with configurable expiration
  • Flexible interceptors for custom request/response handling
  • File upload/download support
  • Configurable timeouts
  • Comprehensive error handling with custom exceptions
• Dependency Injection: Uses injectable and get_it for scalable dependency management.
• State Management: Utilizes flutter_bloc for predictable state management in the presentation layer.
• Model Serialization: Supports json_serializable and freezed for model and state classes.
• Testable: Includes unit, widget, and integration tests following feature-based structure.

---

Getting Started

1. Clone the repository:

   git clone <repo-url>
   cd network_clients
   

2. Install dependencies:

   flutter pub get
   

3. Run the app:

   flutter run
   

---

Usage

The api_kit package provides a powerful and flexible API client. Example:

final api = ApiKit(
  baseUrl: 'https://api.example.com',
  maxRetries: 3,
  retryDelayBase: 1000,
  checkConnectivity: true,
  useCache: true,
  cacheMaxAge: 300,
);

final user = await api.get<User>(
  '/user/1',
  queryParameters: {'lang': 'en'},
  parser: User.fromJson,
);

• All API calls in features go through repositories, which use the api_kit package.
• No direct Dio usage in features; this ensures maintainability and testability.

---

Clean Architecture Overview

The project follows Clean Architecture principles:

Presentation (UI, Blocs)
    ↓
Domain (Use Cases, Entities, Repositories - abstract)
    ↓
Data (Repository Implementations, Models, Data Sources)
    ↓
api_kit (API logic, Dio abstraction)

• Presentation: Handles UI and state management (e.g., Bloc).
• Domain: Pure Dart, business logic, and contracts.
• Data: Implements repositories, handles models and API calls.
• api_kit: Isolates all HTTP logic, reusable across projects.

---

How to Use api_kit in Your Project

1. Add the api_kit package to your project (copy or reference as a local package).

2. Initialize the client:

   final api = ApiKit(
     baseUrl: 'https://api.example.com',
     maxRetries: 3,
     retryDelayBase: 1000,
     checkConnectivity: true,
     useCache: true,
     cacheMaxAge: 300,
   );
   

3. Use generic methods for API calls:

   final user = await api.get<User>(
     '/user/1',
     parser: User.fromJson,
   );
   

4. For paginated responses:

   final paginated = await api.getPaginated<User>(
     '/users',
     queryParameters: {'page': 1, 'limit': 10},
     parser: User.fromJson,
   );
   

5. Handle errors using custom exceptions from the package.

---

Testing

• All layers (data, domain, presentation) are covered by unit, widget, and integration tests.

• Test files are organized by feature in the test/ directory.

• To run all tests:

  flutter test
  

• Recommended: Use mocks for repositories and API responses to isolate tests.

---

Project Structure

• lib/core/: App-level shared constants, environment setup, and base configurations.
• lib/features/: Feature-first modules, each with presentation, domain, and data layers.
• lib/packages/api_kit/: Custom package for HTTP logic, usable across projects.
• lib/shared/: Reusable widgets, extensions, and utilities.
• test/: Unit, widget, and integration tests.

---

FAQ / Troubleshooting

Q: Why can't I use Dio directly in my feature? A: All HTTP logic is isolated in the api_kit package for maintainability and testability. Use repositories and use cases for API calls.

Q: How do I add a new API endpoint? A: Add a method in your repository implementation, use the appropriate api_kit method, and parse the response with your model's fromJson.

Q: How do I handle authentication tokens? A: Use the token management methods in api_kit (e.g., updateToken, clearToken).

Q: My API call throws a custom exception. How do I handle it? A: Catch exceptions in your Bloc or UseCase and map them to user-friendly error states/messages.

Q: How can I configure retry behavior? A: Set maxRetries and retryDelayBase when initializing the ApiKit.

Q: How do I enable caching? A: Set useCache: true and cacheMaxAge when initializing the ApiKit, or per-request with useCache: true.

---

Contributing

Contributions are welcome! Please open issues or submit pull requests for improvements or bug fixes. For major changes, please open an issue first to discuss what you would like to change.

---

License

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