flutter_api_traffic_inspector 0.2.0
flutter_api_traffic_inspector: ^0.2.0 copied to clipboard
A developer-friendly HTTP and WebSocket traffic inspector for Flutter with a real-time tabbed UI, Dio & http support, and SQLite persistence.
Developer #
Chandhuru Varatharaj
Flutter Developer | Open Source Contributor
GitHub: https://github.com/chandhur
flutter_api_traffic_inspector #
A modern, developer-friendly in-app HTTP & WebSocket Inspector for Flutter applications. Inspect network traffic, view formatted JSON payloads, mask sensitive credentials, export cURL commands, and persist request history with SQLite — all without tethering to a computer or proxy.
Features #
- 🚀 Zero Configuration Floating Debug Button: Drag anywhere on the screen, displays real-time request counts and red error indicators.
- 📡 Universal Client Support: Drop-in adapters for both Dio (
ApiInspectorDioInterceptor) and standard Darthttp.Client(ApiInspectorHttpClient). - 🔌 WebSocket Inspector: Wrap
web_socket_channelwithInspectedWebSocketChannelto see connection state and every sent/received message in a chat-style view. - 🔒 Security First: Automatically masks sensitive headers (
Authorization,Cookie,X-API-Key) and body/query fields (password,token,secret) before storage or display. - 💾 SQLite Persistent History: Stores transactions across app restarts with automatic capacity limits (default: 500 records) and pagination.
- 🔍 Real-Time Search & Filtering: Filter by HTTP Method (GET, POST, PUT, DELETE, PATCH), Status Codes (2xx, 4xx, 5xx, Network Errors), Date Range, and URL query text.
- 📋 Developer Tools:
- Pretty-printed JSON viewer with in-viewer search and keyword highlighting.
- One-click Copy as cURL command generation.
- Complete JSON transaction export.
- Key-value tables for headers and query parameters with per-item copy actions.
- 🌗 Light, Dark & System Themes: Material 3 responsive UI with custom status and method badge coloring.
- 🛡️ Production Safe: Easily bypass completely in release builds with
enabled: kDebugMode. Inspector failures never block actual network requests.
Getting Started #
Add flutter_api_traffic_inspector to your pubspec.yaml:
dependencies:
flutter:
sdk: flutter
flutter_api_traffic_inspector: ^0.2.0
Then run:
flutter pub get
Step-by-Step Setup #
1. Initialize in main.dart #
Initialize the inspector inside your main() before calling runApp(). Use kDebugMode to ensure the inspector is active only during development:
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_api_traffic_inspector/flutter_api_traffic_inspector.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await ApiInspector.initialize(
config: const InspectorConfig(
enabled: kDebugMode, // Disabled automatically in release builds
showFloatingButton: true,
enablePersistentHistory: true,
maxHistoryEntries: 500,
),
);
runApp(const MyApp());
}
2. Add the Floating Debug Button Overlay #
Wrap your MaterialApp with ApiInspectorOverlay inside builder:
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'My Application',
// Injects the draggable floating inspector button
builder: (context, child) => ApiInspectorOverlay(
child: child!,
),
home: const HomeScreen(),
);
}
}
3. Attach to Your HTTP Client #
With Dio
Add ApiInspectorDioInterceptor() to your Dio interceptors list:
import 'package:dio/dio.dart';
import 'package:flutter_api_traffic_inspector/flutter_api_traffic_inspector.dart';
final dio = Dio(
BaseOptions(baseUrl: 'https://api.example.com'),
);
// Add the inspector interceptor
dio.interceptors.add(ApiInspectorDioInterceptor());
With Dart http.Client
Wrap your standard client with ApiInspectorHttpClient:
import 'package:http/http.dart' as http;
import 'package:flutter_api_traffic_inspector/flutter_api_traffic_inspector.dart';
final client = ApiInspectorHttpClient(
inner: http.Client(),
);
// Use exactly like standard http.Client
final response = await client.get(
Uri.parse('https://api.example.com/users'),
);
With WebSocket (web_socket_channel)
Replace WebSocketChannel.connect with InspectedWebSocketChannel.connect:
import 'package:flutter_api_traffic_inspector/flutter_api_traffic_inspector.dart';
final channel = InspectedWebSocketChannel.connect(
Uri.parse('wss://echo.websocket.org'),
);
channel.stream.listen(print);
channel.sink.add('hello');
channel.sink.close(1000, 'bye');
Or wrap an existing channel:
final wrapped = InspectedWebSocketChannel(existingChannel, url: 'wss://example.com');
Sessions appear in the WebSocket tab of the dashboard (kept in memory only).
4. Programmatic Navigation (Optional) #
In addition to tapping the floating bubble, you can open the inspector dashboard programmatically anytime from any widget:
ElevatedButton(
onPressed: () => ApiInspector.open(context),
child: const Text('Open API Inspector'),
);
Configuration Reference (InspectorConfig) #
| Property | Type | Default | Description |
|---|---|---|---|
enabled |
bool |
true |
Master switch. When false, all inspection and overlays are completely bypassed. |
showFloatingButton |
bool |
true |
Controls whether the draggable floating debug button is rendered. |
enablePersistentHistory |
bool |
true |
Persists API transaction history to an embedded SQLite database. |
maxHistoryEntries |
int |
500 |
Maximum number of records retained in storage before older entries are pruned. |
themeMode |
InspectorThemeMode |
system |
Default theme: light, dark, or system. |
sensitiveHeaders |
List<String> |
['authorization', 'cookie', 'set-cookie', 'x-api-key'] |
Headers whose values will be masked as ********. |
sensitiveFields |
List<String> |
['password', 'access_token', 'refresh_token', 'token', 'secret'] |
Body keys and query parameters whose values will be masked. |
Security & Reliability Design #
- Masking at the Source: Sensitive data is masked before being passed to storage or UI rendering. Original tokens never exist in SQLite or the dashboard.
- Fail-Safe Networking: All inspection handlers run inside protected error boundaries. If the inspector throws an error, the underlying HTTP request or response will continue without interruption.
- Stream Preservation: Streamed responses and large binary files (images, audio, videos, PDFs) are never consumed prematurely or stored as raw byte arrays.
- Payload Truncation: Strings exceeding 10,000 characters are automatically truncated in the inspector store to maintain smooth 60fps UI rendering.
Example App #
Check out the example/ directory for a complete Flutter app utilizing the DummyJSON Products API with BLoC/Cubit state management, 2-column GridView, infinite scroll pagination, and dynamic details inspection.
cd example
flutter run
License #
This project is licensed under the MIT License - see the LICENSE file for details.