Planned Update

This module is in the queue for a documentation refresh.

API Integration Component

1. Requirements Document

Overview

A high-level wrapper that utilizes the Core HTTP Client to provide a standardized way of defining API endpoints, handling request/response mapping, and managing specific API feature sets (like pagination or file uploads) with minimal boilerplate.

User Stories

  • As a Developer, I want to define an API endpoint by just providing the path and response type.
  • As a Developer, I want automatic error parsing (e.g., converting "400 Bad Request" JSON to a domain error object).
  • As a Developer, I want built-in support for paginated lists without rewriting the scroll logic.

Functional Requirements

  1. Endpoint Definition: Declarative style for defining GET/POST/PUT/DELETE requests.
  2. Response Parsing: Automatic serialization of JSON to Dart models using fromJson factories.
  3. Pagination Wrapper: A standardized response container for paged data (data, meta, links).
  4. Error Transformation: Middleware to convert raw HTTP errors into user-friendly domain exceptions.

2. Technical Document

Architecture

System Architecture

The API Integration Wrapper serves as the base class for all repositories. It abstracts the direct usage of the HTTP client, enforcing a standard pattern for data fetching and error handling across the entire app.

API Design

Base API Usage

class UserApi extends BaseApi {
  UserApi(super.client);
 
  Future<Result<User>> getUser(String id) {
    return get<User>(
      path: '/users/$id',
      decoder: (json) => User.fromJson(json),
    );
  }
 
  Future<Result<PagedList<User>>> getUsers(int page) {
    return getPaged<User>(
      path: '/users',
      query: {'page': page},
      decoder: (json) => User.fromJson(json),
    );
  }
}

Pagination Config

class PagedList<T> {
  final List<T> items;
  final int total;
  final bool hasNext;
  // ...
}