Flutter  

How to Handle API Calls in Flutter Using Dio Package Step-by-Step

Introduction

When building modern mobile applications using Flutter, interacting with APIs is a core requirement. Whether you're fetching user data, submitting forms, or integrating third-party services, efficient API handling becomes critical for performance and user experience. One of the most powerful and flexible libraries for handling HTTP requests in Flutter is Dio. Compared to the basic HTTP package, Dio offers advanced features like interceptors, global configuration, request cancellation, file downloading, and more.

In this guide, you’ll learn step-by-step how to handle API calls in Flutter using Dio, explained in simple and practical terms with real-world examples.

What is Dio in Flutter?

Dio is a third-party HTTP client for Flutter that simplifies network requests and provides advanced capabilities like:

  • Interceptors (for logging, authentication, etc.)

  • Global configuration

  • FormData support

  • Request cancellation

  • Timeout handling

  • File upload/download

Real-life analogy: Think of Dio as a smart delivery manager. Instead of just sending a parcel (API request), it tracks, logs, retries, and manages everything efficiently.

Step 1: Add Dio Dependency

First, you need to include Dio in your Flutter project.

Add this to your pubspec.yaml file:

dependencies:
  dio: ^5.0.0

Then run:

flutter pub get

Step 2: Import Dio Package

Now import Dio in your Dart file where API calls will be handled:

import 'package:dio/dio.dart';

Step 3: Create a Dio Instance

Create a reusable Dio instance for better scalability.

final Dio dio = Dio(
  BaseOptions(
    baseUrl: 'https://api.example.com',
    connectTimeout: const Duration(seconds: 5),
    receiveTimeout: const Duration(seconds: 3),
  ),
);

Real-world example: Instead of setting address and rules every time you order something, you store them once.

Step 4: Make a GET API Call

Future<void> fetchUsers() async {
  try {
    final response = await dio.get('/users');
    print(response.data);
  } catch (e) {
    print('Error: $e');
  }
}

Before vs After:

  • Before: Manual request handling, limited control

  • After: Structured, scalable, and easy-to-manage API calls

Step 5: Make a POST API Call

Future<void> createUser() async {
  try {
    final response = await dio.post(
      '/users',
      data: {
        'name': 'John',
        'email': '[email protected]',
      },
    );
    print(response.data);
  } catch (e) {
    print('Error: $e');
  }
}

Real-life example: Submitting a form in an app like a signup page.

Step 6: Add Interceptors (Very Important)

Interceptors help you log requests, add tokens, and handle errors globally.

dio.interceptors.add(
  InterceptorsWrapper(
    onRequest: (options, handler) {
      options.headers['Authorization'] = 'Bearer YOUR_TOKEN';
      return handler.next(options);
    },
    onResponse: (response, handler) {
      return handler.next(response);
    },
    onError: (DioException e, handler) {
      print('Error: ${e.message}');
      return handler.next(e);
    },
  ),
);

Real-world example: Like a security guard checking ID before entering a building.

Step 7: Handle Errors Properly

try {
  final response = await dio.get('/users');
} on DioException catch (e) {
  if (e.type == DioExceptionType.connectionTimeout) {
    print('Connection Timeout');
  } else if (e.type == DioExceptionType.badResponse) {
    print('Server Error');
  } else {
    print('Unexpected Error');
  }
}

User-visible symptoms if ignored:

  • App crashes

  • No error messages

  • Poor user experience

Step 8: Create a Service Class (Best Practice)

class ApiService {
  final Dio _dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));

  Future<Response> getUsers() async {
    return await _dio.get('/users');
  }
}

This keeps your code clean and maintainable.

Step 9: Use API in UI (Example)

FutureBuilder(
  future: fetchUsers(),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return CircularProgressIndicator();
    }
    return Text('Data Loaded');
  },
)

Advantages of Using Dio

  • Better error handling

  • Clean and scalable architecture

  • Supports interceptors and middleware

  • Easy debugging with logs

  • Timeout and retry support

Disadvantages of Using Dio

  • Slight learning curve for beginners

  • More setup compared to basic HTTP

  • Overkill for very small apps

Common Mistakes to Avoid

  • Not handling exceptions properly

  • Hardcoding API URLs everywhere

  • Ignoring interceptors

  • Blocking UI during API calls

Summary

Handling API calls in Flutter using Dio makes your application more structured, scalable, and production-ready. By setting up a centralized Dio instance, using interceptors for authentication and logging, and properly managing errors, you can significantly improve both developer experience and app performance. In real-world scenarios, this approach helps avoid crashes, ensures smooth data flow, and makes your code easier to maintain as your application grows.

Membership not found