fast_dio

Dio-based HTTP client for Flutter with the same developer experience as fast_http.

It provides a typed request layer (GenericRequest), global headers, structured errors, multipart uploads, query parameters, download/stream support, and Dio interceptors — without exposing low-level Dio setup in every feature.

Features

Same API pattern as fast_http: FastDio, FastDioHeader, RequestApi, GenericRequest
JSON parsing with getObject, getList, getResponse, getBytes
Global and per-request headers (static + async dynamic headers)
Centralized error handling with ServerException and RequestErrorModel
Status-code hooks for auth flows (401, 406, etc.)
Query parameters support
Multipart uploads with named fields via RequestFile
Per-request Dio options: timeouts, CancelToken, progress callbacks
File download and streamed responses
Interceptor helpers and built-in logging support
Exports fpdart for functional error handling

Getting started

Add the dependency:

dependencies:
  fast_dio: ^0.0.1

Or from GitHub:

dependencies:
  fast_dio:
    git:
      url: https://github.com/El-sayed-mahmoud/fast_dio.git

Usage

Initialize

import 'package:fast_dio/fast_dio.dart';

void setupHttp() {
  FastDio.initialize(
    genericDataKey: 'data',
    checkStatusKey: 'status',
    checkResponseIsSuccess: (response) => true,
    getErrorMessageFromResponse: (response) {
      return response['message']?.toString() ?? 'An error occurred';
    },
    onGetResponseStatusCode: (statusCode) {
      if (statusCode == 401) {
        // handle logout / redirect
      }
    },
    connectTimeout: const Duration(seconds: 30),
    receiveTimeout: const Duration(seconds: 60),
  );

  FastDioHeader().addHeader('Accept', '*/*');
  FastDioHeader().addHeader('content-type', 'application/json');
  FastDioHeader().addDynamicHeader(
    'Authorization',
    () async => 'Bearer YOUR_TOKEN',
  );

  FastDio.addLogInterceptor(responseBody: true);
}

GET object

final request = GenericRequest<UserModel>(
  fromMap: UserModel.fromJson,
  method: RequestApi.get(
    url: 'https://api.example.com/user/1',
    queryParameters: {'lang': 'ar'},
  ),
);

final user = await request.getObject();

POST with body

final request = GenericRequest<LoginResponse>(
  fromMap: LoginResponse.fromJson,
  method: RequestApi.post(
    url: 'https://api.example.com/login',
    body: {'email': email, 'password': password},
  ),
);

final response = await request.getObject();

Upload file

await RequestApi.post(
  url: 'https://api.example.com/upload',
  body: {'title': 'avatar'},
  isMultipartRequest: true,
  files: [
    RequestFile(
      field: 'file',
      file: await MultipartFile.fromFile(path, filename: 'avatar.jpg'),
    ),
  ],
).request();

Download file

final path = await RequestApi.get(
  url: 'https://api.example.com/report.pdf',
).download(savePath: '/path/to/report.pdf');

Stream response

final body = await RequestApi.get(
  url: 'https://api.example.com/stream',
).requestStream();

final stream = body.stream;

Progress

FastDio.progressUpdates.listen((progress) {
  print('${progress.direction}: ${progress.percentage}%');
});

API overview

fast_http	fast_dio
`FastHttp`	`FastDio`
`FastHttpHeader`	`FastDioHeader`
`RequestApi`	`RequestApi`
`GenericRequest`	`GenericRequest`
`dartz` export	`fpdart` export

Additional information

Source code: GitHub
Issues: GitHub Issues