🚀 zeba_academy_api_client

Enterprise‑grade REST and GraphQL API client for Flutter and Dart applications.

zeba_academy_api_client provides a powerful networking layer with interceptors, retry logic, caching, offline support, logging, file upload/download, and pagination helpers.

Designed for production apps, EdTech platforms, SaaS apps, and large Flutter projects.

---

✨ Features

✅ REST API wrapper

✅ GraphQL support

✅ Interceptor system (similar to Dio)

✅ Automatic retry logic

✅ Token refresh handling

✅ Centralized error handling

✅ Request / response logging

✅ Timeout configuration

✅ In‑memory request caching

✅ Offline‑ready architecture

✅ File upload

✅ File download

✅ API mocking for testing

✅ Pagination helpers

---

📦 Installation

Add the dependency in your pubspec.yaml:

dependencies:
  zeba_academy_api_client: ^1.0.0

Then run:

flutter pub get

---

🚀 Basic Usage

import 'package:zeba_academy_api_client/zeba_academy_api_client.dart';

final client = ApiClient(
  config: ApiConfig(
    baseUrl: "https://jsonplaceholder.typicode.com",
  ),
);

final response = await client.get("/users");

print(response.data);

---

⚙️ Configuration

You can configure timeout, retries, headers and more.

final client = ApiClient(
  config: ApiConfig(
    baseUrl: "https://api.example.com",
    timeout: Duration(seconds: 15),
    maxRetries: 3,
  ),
);

---

🔐 Authentication Interceptor

Interceptors allow modifying requests globally.

class AuthInterceptor extends ApiInterceptor {
  final String token;

  AuthInterceptor(this.token);

  @override
  Future<void> onRequest(RequestContext ctx) async {
    ctx.headers['Authorization'] = 'Bearer $token';
  }
}

Usage:

final client = ApiClient(
  config: ApiConfig(baseUrl: "https://api.example.com"),
  interceptors: [
    AuthInterceptor("your_token"),
  ],
);

---

📊 Logging Interceptor

Logs all requests and responses.

final client = ApiClient(
  config: ApiConfig(baseUrl: "https://api.example.com"),
  interceptors: [
    LoggingInterceptor(),
  ],
);

---

🔁 Retry Logic

Automatic retries for failed network calls.

final client = ApiClient(
  config: ApiConfig(
    baseUrl: "https://api.example.com",
    maxRetries: 3,
  ),
);

---

🧠 Request Caching

Enable in‑memory caching.

final client = ApiClient(
  config: ApiConfig(baseUrl: "https://api.example.com"),
  cache: MemoryCache(),
);

---

📡 GraphQL Support

Execute GraphQL queries easily.

final response = await client.graphql(
  query: """
  query GetUsers {
    users {
      id
      name
    }
  }
  """,
);

---

📤 File Upload

await client.uploadFile(
  endpoint: "/upload",
  filePath: "path/to/file.png",
);

---

📥 File Download

await client.downloadFile(
  url: "/files/report.pdf",
  savePath: "downloads/report.pdf",
);

---

📄 Pagination Helper

Simplifies paginated APIs.

final page = await client.getPage(
  endpoint: "/users",
  page: 1,
  limit: 10,
);

---

🧪 API Mocking

Useful for development and testing.

final client = ApiClient(
  config: ApiConfig(baseUrl: "https://api.example.com"),
  mockResponses: {
    "/users": [
      {"id": 1, "name": "Test User"}
    ]
  },
);

---

📱 Example UI

This package includes an example Flutter app demonstrating:

• API calls • Loading state • Error handling • Response rendering

---

📸 Screenshots

Example Flutter UI demonstrating API request, response rendering, and error handling using zeba_academy_api_client.

Then reference the screenshot in pubspec.yaml.

screenshots:
  - description: API client demo
    path: screenshots/api_client_demo.png

---

🧩 Architecture

The package is structured using modular networking layers:

lib/
 ├── src/
 │   ├── api_client.dart
 │   ├── api_config.dart
 │   ├── api_response.dart
 │   ├── api_exception.dart
 │   ├── interceptors/
 │   ├── cache/
 │   ├── graphql/
 │   ├── pagination/
 │   └── retry/

This architecture ensures the client is scalable, maintainable, and production ready.

---

🧪 Testing

Run tests using:

flutter test

---

📜 License

This project is licensed under the GPL‑3.0 License.

---

🏫 Zeba Academy

Built with ❤️ for modern Flutter development and EdTech platforms.