http_interceptor

This is a plugin that lets you intercept the different requests and responses from Dart's http package. You can use to add headers, modify query params, or print a log of the response.

Quick Reference

Upgrading from 2.x? See the 3.0.0 migration guide.

http_interceptor

Installation

Include the package with the latest version available in your pubspec.yaml.

dart
http_interceptor: <latest>

Features

🚦 Intercept & change unstreamed requests and responses.
✨ Retrying requests when an error occurs or when the response does not match the desired (useful for handling custom error responses).
👓 GET requests with separated parameters.
⚡️ Standard Response.bodyBytes for encoding or decoding as needed.
📦 Convenience helpers to decode JSON responses and map them into your own models.
🙌🏼 Array parameters on requests.
🖋 Supports self-signed certificates (except on Flutter Web).
🍦 Compatible with vanilla Dart projects or Flutter projects.
🎉 Null-safety.
⏲ Timeout configuration with duration and timeout functions.
⏳ Configure the delay for each retry attempt.

Usage

dart
import 'package:http_interceptor/http_interceptor.dart';

Building your own interceptor

Implement HttpInterceptor to add logging, headers, error handling, and more. The interface has four methods:

interceptRequest – runs before the request is sent. Return the (possibly modified) request.
interceptResponse – runs after the response is received. Return the (possibly modified) response.
shouldInterceptRequest / shouldInterceptResponse – return false to skip interception for that request/response (default true).

All methods support FutureOr so you can use sync or async. Modify the request/response in place and return it, or return a new instance.

Logging interceptor:

dart
class LoggerInterceptor implements HttpInterceptor {
  @override
  BaseRequest interceptRequest({required BaseRequest request}) {
    print('----- Request -----');
    print(request.toString());
    return request;
  }

  @override
  BaseResponse interceptResponse({required BaseResponse response}) {
    print('----- Response -----');
    print('Code: ${response.statusCode}');
    if (response is Response) {
      print(response.body);
    }
    return response;
  }
}

Adding headers / query params (in-place mutation):

dart
class WeatherApiInterceptor implements HttpInterceptor {
  @override
  BaseRequest interceptRequest({required BaseRequest request}) {
    final url = request.url.replace(
      queryParameters: {
        ...request.url.queryParameters,
        'appid': apiKey,
        'units': 'metric',
      },
    );
    return Request(request.method, url)
      ..headers.addAll(request.headers)
      ..headers[HttpHeaders.contentTypeHeader] = 'application/json';
  }

  @override
  BaseResponse interceptResponse({required BaseResponse response}) => response;
}

Using your interceptor

Now that you actually have your interceptor implemented, now you need to use it. There are two general ways in which you can use them: by using the InterceptedHttp to do separate connections for different requests or using a InterceptedClient for keeping a connection alive while making the different http calls. The ideal place to use them is in the service/provider class or the repository class (if you are not using services or providers); if you don't know about the repository pattern you can just google it and you'll know what I'm talking about. 😉

Using interceptors with Client

Normally, this approach is taken because of its ability to be tested and mocked.

Here is an example with a repository using the InterceptedClient class.

dart
class WeatherRepository {
  final client = InterceptedClient.build(
    interceptors: [WeatherApiInterceptor()],
  );

  Future<Map<String, dynamic>> fetchCityWeather(int id) async {
    final response = await client.get(
      '$baseUrl/weather'.toUri(),
      params: {'id': '$id'},
    );
    if (response.statusCode == 200) {
      // Built-in Response JSON helpers:
      return response.jsonMap;
    }
    throw Exception('Error while fetching.\\n${response.body}');
  }

}

Using interceptors without Client

This is mostly the straight forward approach for a one-and-only call that you might need intercepted.

Here is an example with a repository using the InterceptedHttp class.

dart
class WeatherRepository {

    Future<Map<String, dynamic>> fetchCityWeather(int id) async {
    final http = InterceptedHttp.build(interceptors: [WeatherApiInterceptor()]);
    final response = await http.get(
      '$baseUrl/weather'.toUri(),
      params: {'id': '$id'},
    );
    if (response.statusCode == 200) {
      // Built-in Response JSON helpers:
      return response.jsonMap;
    }
    return Future.error(
      'Error while fetching.',
      StackTrace.fromString(response.body),
    );
  }

}

Working with JSON responses

The ResponseBodyDecoding extension adds a few lightweight helpers on Response for common JSON use cases:

dart
final response = await client.get(
  '$baseUrl/weather'.toUri(),
  params: {'id': '$id'},
);

// Dynamically-typed JSON value (Map/List/primitive or null on empty body).
final Object? json = response.jsonBody;

// JSON object as a map (throws if body is empty or not a JSON object).
final Map<String, dynamic> data = response.jsonMap;

// JSON array as a list (throws if body is empty or not a JSON array).
final List<dynamic> items = response.jsonList;

Decoding responses into models

The ResponseBodyDecoding extension provides helpers to turn JSON responses into strongly-typed models with minimal boilerplate.

dart
class Weather {
  final String description;
  final double temperature;

  const Weather({
    required this.description,
    required this.temperature,
  });

  factory Weather.fromJson(Map<String, dynamic> json) {
    return Weather(
      description: (json['weather'] as List).first['description'] as String,
      temperature: (json['main']['temp'] as num).toDouble(),
    );
  }
}

Future<Weather> fetchCityWeather(int id) async {
  final client = InterceptedClient.build(
    interceptors: [WeatherApiInterceptor()],
  );

  final response = await client.get(
    '$baseUrl/weather'.toUri(),
    params: {'id': '$id'},
  );

  if (response.statusCode == 200) {
    // Use the built-in JSON mapper:
    return response.decodeJson(
      (json) => Weather.fromJson(json as Map<String, dynamic>),
    );
  }

  throw Exception('Error while fetching.\n${response.body}');
}

Retrying requests

Sometimes you need to retry a request due to different circumstances, an expired token is a really good example. Here's how you could potentially implement an expired token retry policy with http_interceptor.

dart
class ExpiredTokenRetryPolicy extends RetryPolicy {
  @override
  int get maxRetryAttempts => 2;

  @override
  bool shouldAttemptRetryOnException(Exception reason, BaseRequest request) {
    // Log the exception for debugging
    print('Request failed: ${reason.toString()}');
    print('Request URL: ${request.url}');
    
    // Retry on network exceptions, but not on client errors
    return reason is SocketException || reason is TimeoutException;
  }

  @override
  Future<bool> shouldAttemptRetryOnResponse(BaseResponse response) async {
    if (response.statusCode == 401) {
      // Perform your token refresh here.
      print('Token expired, refreshing...');
      
      return true;
    }

    return false;
  }
}

You can also set the maximum amount of retry attempts with maxRetryAttempts property or override the shouldAttemptRetryOnException if you want to retry the request after it failed with an exception.

RetryPolicy Interface

The RetryPolicy abstract class provides the following methods that you can override:

shouldAttemptRetryOnException(Exception reason, BaseRequest request): Called when an exception occurs during the request. Return true to retry, false to fail immediately.
shouldAttemptRetryOnResponse(BaseResponse response): Called after receiving a response. Return true to retry, false to accept the response.
maxRetryAttempts: The maximum number of retry attempts (default: 1).
delayRetryAttemptOnException({required int retryAttempt}): Delay before retrying after an exception (default: no delay).
delayRetryAttemptOnResponse({required int retryAttempt}): Delay before retrying after a response (default: no delay).

Using Retry Policies

To use a retry policy, pass it to the InterceptedClient or InterceptedHttp:

dart
final client = InterceptedClient.build(
  interceptors: [WeatherApiInterceptor()],
  retryPolicy: ExpiredTokenRetryPolicy(),
);

Sometimes it is helpful to have a cool-down phase between multiple requests. This delay could for example also differ between the first and the second retry attempt as shown in the following example.

dart
class ExpiredTokenRetryPolicy extends RetryPolicy {
  @override
  int get maxRetryAttempts => 3;

  @override
  bool shouldAttemptRetryOnException(Exception reason, BaseRequest request) {
    // Only retry on network-related exceptions
    return reason is SocketException || reason is TimeoutException;
  }

  @override
  Future<bool> shouldAttemptRetryOnResponse(BaseResponse response) async {
    // Retry on server errors (5xx) and authentication errors (401)
    return response.statusCode >= 500 || response.statusCode == 401;
  }

  @override
  Duration delayRetryAttemptOnException({required int retryAttempt}) {
    // Exponential backoff for exceptions
    return Duration(milliseconds: (250 * math.pow(2.0, retryAttempt - 1)).round());
  }

  @override
  Duration delayRetryAttemptOnResponse({required int retryAttempt}) {
    // Exponential backoff for response-based retries
    return Duration(milliseconds: (250 * math.pow(2.0, retryAttempt - 1)).round());
  }
}

Using self signed certificates

You can achieve support for self-signed certificates by providing InterceptedHttp or InterceptedClient with the client parameter when using the build method on either of those, it should look something like this:

InterceptedClient

dart
Client client = InterceptedClient.build(
  interceptors: [
    WeatherApiInterceptor(),
  ],
  client: IOClient(
    HttpClient()
      ..badCertificateCallback = badCertificateCallback
      ..findProxy = findProxy,
  );
);

InterceptedHttp

dart
final http = InterceptedHttp.build(
  interceptors: [
    WeatherApiInterceptor(),
  ],
  client: IOClient(
    HttpClient()
      ..badCertificateCallback = badCertificateCallback
      ..findProxy = findProxy,
  );
);

Note: It is important to know that since both HttpClient and IOClient are part of dart:io package, this will not be a feature that you can perform on Flutter Web (due to BrowserClient and browser limitations).

Roadmap

Check out our roadmap here.

We migrated our roadmap to better suit the needs for development since we use ClickUp as our task management tool.

Troubleshooting

Open an issue and tell me, I will be happy to help you out as soon as I can.

Contributions

Contributions are always welcomed and encouraged, we will always give you credit for your work on this section. If you are interested in maintaining the project on a regular basis drop me a line at me@codingale.dev.

Contributors

Thanks to all the wonderful people contributing to improve this package. Check the Emoji Key for reference on what means what!

<table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://codingale.dev"><img src="https://avatars.githubusercontent.com/u/12262852?v=3?s=100" width="100px;" alt="Alejandro Ulate Fallas"/> Alejandro Ulate Fallas</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=codingalecr" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=codingalecr" title="Documentation">📖</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=codingalecr" title="Tests">⚠️</a> <a href="#ideas-codingalecr" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-codingalecr" title="Maintenance">🚧</a></td> <td align="center" valign="top" width="14.28%"><a href="https://softmaestri.com/en/"><img src="https://avatars.githubusercontent.com/u/4113558?v=4?s=100" width="100px;" alt="Konstantin Serov"/> Konstantin Serov</a> <a href="#ideas-caseyryan" title="Ideas, Planning, & Feedback">🤔</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/Virus1908"><img src="https://avatars.githubusercontent.com/u/4580305?v=4?s=100" width="100px;" alt="Virus1908"/> Virus1908</a> <a href="#ideas-Virus1908" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=Virus1908" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=Virus1908" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/AsynchronySuperWes"><img src="https://avatars.githubusercontent.com/u/13644053?v=4?s=100" width="100px;" alt="Wes Ehrlichman"/> Wes Ehrlichman</a> <a href="#ideas-AsynchronySuperWes" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=AsynchronySuperWes" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=AsynchronySuperWes" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/jlubeck"><img src="https://avatars.githubusercontent.com/u/3067603?v=4?s=100" width="100px;" alt="Jan Lübeck"/> Jan Lübeck</a> <a href="#ideas-jlubeck" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=jlubeck" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=jlubeck" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/lucalves"><img src="https://avatars.githubusercontent.com/u/17712401?v=4?s=100" width="100px;" alt="Lucas Alves"/> Lucas Alves</a> <a href="#ideas-lucalves" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=lucalves" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=lucalves" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/stewemetal"><img src="https://avatars.githubusercontent.com/u/5860632?v=4?s=100" width="100px;" alt="István Juhos"/> István Juhos</a> <a href="#ideas-stewemetal" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=stewemetal" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=stewemetal" title="Tests">⚠️</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/shyndman"><img src="https://avatars.githubusercontent.com/u/42326?v=4?s=100" width="100px;" alt="Scott Hyndman"/> Scott Hyndman</a> <a href="#ideas-shyndman" title="Ideas, Planning, & Feedback">🤔</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/II11II"><img src="https://avatars.githubusercontent.com/u/45257709?v=4?s=100" width="100px;" alt="Islam Akhrarov"/> Islam Akhrarov</a> <a href="#ideas-II11II" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=II11II" title="Tests">⚠️</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=II11II" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/meysammahfouzi"><img src="https://avatars.githubusercontent.com/u/14848008?v=4?s=100" width="100px;" alt="Meysam"/> Meysam</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=meysammahfouzi" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/Mawi137"><img src="https://avatars.githubusercontent.com/u/5464100?v=4?s=100" width="100px;" alt="Martijn"/> Martijn</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=Mawi137" title="Tests">⚠️</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=Mawi137" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/MaciejZuk"><img src="https://avatars.githubusercontent.com/u/78476165?v=4?s=100" width="100px;" alt="MaciejZuk"/> MaciejZuk</a> <a href="https://github.com/CodingAleCR/http_interceptor/issues?q=author%3AMaciejZuk" title="Bug reports">🐛</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/lukaskurz"><img src="https://avatars.githubusercontent.com/u/22956519?v=4?s=100" width="100px;" alt="Lukas Kurz"/> Lukas Kurz</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=lukaskurz" title="Tests">⚠️</a> <a href="#ideas-lukaskurz" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=lukaskurz" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/vixez"><img src="https://avatars.githubusercontent.com/u/3032294?v=4?s=100" width="100px;" alt="Glenn Ruysschaert"/> Glenn Ruysschaert</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=vixez" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=vixez" title="Tests">⚠️</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/dexcell"><img src="https://avatars.githubusercontent.com/u/41800?v=4?s=100" width="100px;" alt="Erick"/> Erick</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=dexcell" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=dexcell" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/javiermrz"><img src="https://avatars.githubusercontent.com/u/46677628?v=4?s=100" width="100px;" alt="javiermrz"/> javiermrz</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=javiermrz" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/ntimesc"><img src="https://avatars.githubusercontent.com/u/5063898?v=4?s=100" width="100px;" alt="nihar"/> nihar</a> <a href="#ideas-ntimesc" title="Ideas, Planning, & Feedback">🤔</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/ayyysh04"><img src="https://avatars.githubusercontent.com/u/74104690?v=4?s=100" width="100px;" alt="Ayush Yadav"/> Ayush Yadav</a> <a href="#ideas-ayyysh04" title="Ideas, Planning, & Feedback">🤔</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/shittyday"><img src="https://avatars.githubusercontent.com/u/88209828?v=4?s=100" width="100px;" alt="Alex"/> Alex</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=shittyday" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/iruizr7"><img src="https://avatars.githubusercontent.com/u/65398602?v=4?s=100" width="100px;" alt="Iñigo R."/> Iñigo R.</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=iruizr7" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/td2thinh"><img src="https://avatars.githubusercontent.com/u/75013885?v=4?s=100" width="100px;" alt="Thinh TRUONG"/> Thinh TRUONG</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=td2thinh" title="Code">💻</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/KacperKluka"><img src="https://avatars.githubusercontent.com/u/62378170?v=4?s=100" width="100px;" alt="KacperKluka"/> KacperKluka</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=KacperKluka" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/techouse"><img src="https://avatars.githubusercontent.com/u/1174328?v=4?s=100" width="100px;" alt="Klemen Tusar"/> Klemen Tusar</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=techouse" title="Code">💻</a> <a href="https://github.com/CodingAleCR/http_interceptor/commits?author=techouse" title="Documentation">📖</a></td> </tr> </tbody> </table>