Introduction to APIs in Flutter

APIs (Application Programming Interfaces) are an essential part of modern Flutter application development. APIs allow a Flutter application to communicate with external servers, databases, cloud services, authentication systems, payment gateways, and other applications over a network.

In a typical Flutter application, the user interacts with the UI, the application sends a request to an API, the server processes the request, and the API returns a response. Flutter can then process that response and display the required information to the user.

Flutter applications commonly use the http package for making HTTP requests across supported platforms.

1. What is an API?

API stands for Application Programming Interface. An API is a set of rules and endpoints that allows one software application to communicate with another software system.

For example, a weather application does not usually store live weather information inside the Flutter application. Instead, it sends a request to a weather API. The API processes the request and returns weather information, usually in JSON format.

Simple API Example

GET https://example.com/api/users

The above API endpoint may return a list of users from a remote server.

2. Why APIs Are Important in Flutter

APIs are important because most real-world applications need data that is stored outside the application.

• Fetch data from a remote server.
• Send user information to a backend.
• Implement login and registration.
• Retrieve products from an e-commerce server.
• Display news, weather, or social media data.
• Create, update, and delete records.
• Upload images and files.
• Communicate with cloud services.
• Connect applications with payment systems.
• Synchronize application data with a backend database.

3. How an API Works with Flutter

The basic communication process between a Flutter application and an API can be represented as follows:

Flutter Application
       |
       | HTTP Request
       v
   API Server
       |
       | Process Request
       v
    Database
       |
       | Data
       v
   API Server
       |
       | HTTP Response
       v
Flutter Application
       |
       | Parse JSON
       v
    UI Screen

Typical Flow

1. User performs an action.
2. Flutter creates an API request.
3. The request is sent to the server.
4. The server processes the request.
5. The server may read or modify database information.
6. The server sends a response.
7. Flutter receives the response.
8. The response is decoded, usually from JSON.
9. The data is converted into Dart objects when appropriate.
10. Flutter updates the UI.

4. What is a REST API?

REST stands for Representational State Transfer. REST is an architectural style commonly used for creating web APIs.

A REST API generally exposes resources through URLs and uses HTTP methods to perform operations on those resources.

Example

https://api.example.com/users
https://api.example.com/products
https://api.example.com/orders

Each endpoint represents a resource that the application can interact with.

5. Common HTTP Methods Used with APIs

6. Setting Up API Communication in Flutter

The http package provides a Future-based API for making HTTP requests.

Install the HTTP Package

flutter pub add http

You can also add the dependency manually in pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  http: ^1.6.0

Use the current compatible package version for your project's Dart and Flutter SDK.

Import the Package

import 'package:http/http.dart' as http;

7. Android Internet Permission

When deploying a Flutter application to Android, the application must declare internet access in its Android manifest.

The permission is normally added in:

android/app/src/main/AndroidManifest.xml

For Android applications that need network access, make sure the required Internet permission is declared in the manifest:

<uses-permission android:name="android.permission.INTERNET" />

8. Making a Simple GET API Request

A GET request is used to retrieve information from an API.

import 'package:http/http.dart' as http;

Future<http.Response> fetchPost() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
  );
  return response;
}

In this example, http.get() sends a GET request to the specified API endpoint.

9. Understanding Uri

The Uri class represents a Uniform Resource Identifier. Flutter applications commonly use Uri.parse() or Uri.https() to create API URLs.

Using Uri.parse()

final url = Uri.parse(
  'https://jsonplaceholder.typicode.com/posts/1',
);

Using Uri.https()

final url = Uri.https(
  'jsonplaceholder.typicode.com',
  '/posts/1',
);

Using Uri.https() can be especially useful when constructing URLs with query parameters.

10. Understanding async and await

API requests take time because the application must communicate with a remote server. Dart uses asynchronous programming to prevent the UI from being blocked while waiting for a response.

Future<void> getData() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
  );
  print(response.body);
}

• Future represents a value that will become available later.
• async allows a function to perform asynchronous operations.
• await waits for an asynchronous operation to complete.

11. Understanding HTTP Response

An HTTP request returns an http.Response object.

final response = await http.get(
  Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
);

print(response.statusCode);
print(response.body);
print(response.headers);

Important Response Properties

12. HTTP Status Codes

Status codes help Flutter determine whether an API request succeeded or failed.

13. Checking the Status Code

final response = await http.get(
  Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
);

if (response.statusCode == 200) {
  print('Request successful');
  print(response.body);
} else {
  print('Request failed: ${response.statusCode}');
}

Always check the response status when your application needs to distinguish successful responses from errors.

14. Understanding JSON

Most REST APIs return data in JSON (JavaScript Object Notation) format. JSON represents data using objects, arrays, strings, numbers, booleans, and null values.

Example JSON Object

{
  "id": 1,
  "title": "Flutter API Tutorial",
  "completed": false
}

Example JSON Array

[
  {
    "id": 1,
    "name": "John"
  },
  {
    "id": 2,
    "name": "Sarah"
  }
]

15. Decoding JSON in Flutter

Dart provides the dart:convert library for JSON encoding and decoding.

import 'dart:convert';

final data = jsonDecode(response.body);

print(data['id']);
print(data['title']);

The result of jsonDecode() may be a Map, List, or another supported JSON value depending on the response.

16. Creating a Dart Model

For larger applications, it is better to convert JSON data into Dart model objects instead of working with raw maps throughout the UI.

class Post {
  final int id;
  final String title;
  final String body;

  Post({
    required this.id,
    required this.title,
    required this.body,
  });

  factory Post.fromJson(Map<String, dynamic> json) {
    return Post(
      id: json['id'],
      title: json['title'],
      body: json['body'],
    );
  }
}

17. Converting API Response into a Model

Future<Post> fetchPost() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
  );

  if (response.statusCode == 200) {
    final jsonData = jsonDecode(response.body);
    return Post.fromJson(jsonData);
  }

  throw Exception('Failed to load post');
}

This approach separates API data from the UI and makes the application easier to maintain.

18. Sending Data with POST

A POST request is commonly used to create a new resource or submit information to a server.

Future<http.Response> createPost() async {
  final response = await http.post(
    Uri.parse('https://jsonplaceholder.typicode.com/posts'),
    headers: {
      'Content-Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode({
      'title': 'Flutter API',
      'body': 'Learning API integration',
      'userId': 1,
    }),
  );

  return response;
}

The request body is encoded as JSON before being sent to the server.

19. Understanding HTTP Headers

HTTP headers provide additional information about a request or response.

Common Headers

Example

final response = await http.get(
  Uri.parse('https://example.com/api/profile'),
  headers: {
    'Accept': 'application/json',
  },
);

20. Sending JSON Data

When an API expects JSON, set the appropriate content type and encode the Dart object using jsonEncode().

final data = {
  'name': 'John',
  'email': '[email protected]',
};

final response = await http.post(
  Uri.parse('https://example.com/api/users'),
  headers: {
    'Content-Type': 'application/json',
  },
  body: jsonEncode(data),
);

21. PUT Request

PUT is commonly used when an API expects an update or replacement of an existing resource.

final response = await http.put(
  Uri.parse('https://example.com/api/users/1'),
  headers: {
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'name': 'John Updated',
    'email': '[email protected]',
  }),
);

22. PATCH Request

PATCH is commonly used for partial updates.

final response = await http.patch(
  Uri.parse('https://example.com/api/users/1'),
  headers: {
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'email': '[email protected]',
  }),
);

23. DELETE Request

DELETE is used to remove a resource from a server.

final response = await http.delete(
  Uri.parse('https://example.com/api/users/1'),
);

if (response.statusCode >= 200 && response.statusCode < 300) {
  print('User deleted successfully');
}

24. API Authentication

Many APIs require authentication before allowing access to protected resources. One common approach is to send an authentication token through the Authorization header.

final response = await http.get(
  Uri.parse('https://example.com/api/profile'),
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Accept': 'application/json',
  },
);

Security Note: Never hard-code real production secrets, private keys, or sensitive credentials directly into application source code.

25. Query Parameters

Query parameters are values added to a URL to filter, search, sort, or customize API results.

Example URL

https://example.com/api/products?category=mobile&page=1

Using Uri.https()

final uri = Uri.https(
  'example.com',
  '/api/products',
  {
    'category': 'mobile',
    'page': '1',
  },
);

final response = await http.get(uri);

26. Path Parameters

Path parameters are commonly used to identify a specific resource.

final userId = 25;

final uri = Uri.parse(
  'https://example.com/api/users/$userId',
);

final response = await http.get(uri);

The generated URL becomes:

https://example.com/api/users/25

27. Handling Exceptions

Network requests can fail because of connectivity problems, invalid URLs, server errors, timeouts, or other issues. Use try-catch to handle exceptions.

Future<void> fetchData() async {
  try {
    final response = await http.get(
      Uri.parse('https://example.com/api/data'),
    );

    if (response.statusCode == 200) {
      print(response.body);
    } else {
      print('Server error: ${response.statusCode}');
    }
  } catch (e) {
    print('Network error: $e');
  }
}

28. API Request Timeout

Applications should avoid waiting indefinitely for a network request.

final response = await http
    .get(Uri.parse('https://example.com/api/data'))
    .timeout(
      const Duration(seconds: 10),
    );

You can catch timeout-related exceptions and show a useful message or retry option to the user.

29. Using FutureBuilder with APIs

FutureBuilder is useful when a screen needs to display the result of a Future while handling loading, success, and error states.

API Function

Future<Post> fetchPost() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
  );

  if (response.statusCode == 200) {
    return Post.fromJson(jsonDecode(response.body));
  }

  throw Exception('Failed to load post');
}

FutureBuilder

FutureBuilder<Post>(
  future: fetchPost(),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }

    if (snapshot.hasError) {
      return Text('Error: ${snapshot.error}');
    }

    if (!snapshot.hasData) {
      return const Text('No data available');
    }

    return Text(snapshot.data!.title);
  },
)

30. Avoid Calling API Directly Inside build()

Calling an API directly inside the build() method can cause repeated network requests because Flutter may call build() multiple times.

Incorrect Approach

@override
Widget build(BuildContext context) {
  fetchPost();
  return const Text('Loading...');
}

Better Approach

late Future<Post> postFuture;

@override
void initState() {
  super.initState();
  postFuture = fetchPost();
}

The Future can then be supplied to FutureBuilder.

31. Fetching a List from an API

Many APIs return arrays containing multiple objects.

Future<List<Post>> fetchPosts() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts'),
  );

  if (response.statusCode == 200) {
    final List<dynamic> data = jsonDecode(response.body);

    return data
        .map((json) => Post.fromJson(json))
        .toList();
  }

  throw Exception('Failed to load posts');
}

32. Displaying API Data in a ListView

FutureBuilder<List<Post>>(
  future: fetchPosts(),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const Center(
        child: CircularProgressIndicator(),
      );
    }

    if (snapshot.hasError) {
      return Center(
        child: Text('Error: ${snapshot.error}'),
      );
    }

    final posts = snapshot.data ?? [];

    return ListView.builder(
      itemCount: posts.length,
      itemBuilder: (context, index) {
        final post = posts[index];

        return ListTile(
          title: Text(post.title),
          subtitle: Text(post.body),
        );
      },
    );
  },
)

33. Creating an API Service Class

Instead of placing all API logic inside widgets, create a service class.

class ApiService {
  final String baseUrl = 'https://example.com/api';

  Future<List<Post>> getPosts() async {
    final response = await http.get(
      Uri.parse('$baseUrl/posts'),
    );

    if (response.statusCode == 200) {
      final List<dynamic> data = jsonDecode(response.body);

      return data
          .map((json) => Post.fromJson(json))
          .toList();
    }

    throw Exception('Failed to fetch posts');
  }
}

This keeps networking logic separate from presentation code.

34. Separating API, Model, and UI Layers

A scalable Flutter application should separate different responsibilities.

lib/
├── models/
│   └── post.dart
├── services/
│   └── api_service.dart
├── repositories/
│   └── post_repository.dart
├── screens/
│   └── post_screen.dart
├── widgets/
│   └── post_card.dart
└── main.dart

Responsibilities

35. API Loading, Success, Empty, and Error States

A professional application should handle different API states.

36. Retry API Requests

Providing a retry action can improve the user experience when a temporary network failure occurs.

Future<void> retryRequest() async {
  try {
    final response = await http.get(
      Uri.parse('https://example.com/api/data'),
    );

    if (response.statusCode == 200) {
      print(response.body);
    } else {
      print('Request failed');
    }
  } catch (e) {
    print('Try again later');
  }
}

37. Pull-to-Refresh

Flutter's RefreshIndicator can be used to refresh API data when the user pulls down on a scrollable widget.

RefreshIndicator(
  onRefresh: () async {
    await fetchPosts();
  },
  child: ListView(
    children: const [
      ListTile(title: Text('Post 1')),
      ListTile(title: Text('Post 2')),
    ],
  ),
)

38. Using http.Client

The http.Client interface is useful when an application makes multiple requests or when the HTTP client needs to be injected for testing.

final client = http.Client();

try {
  final response = await client.get(
    Uri.parse('https://example.com/api/data'),
  );

  print(response.body);
} finally {
  client.close();
}

Using a client explicitly can also make API services easier to test because a mock client can be supplied.

39. Background JSON Processing

Large JSON responses can require significant processing. For large datasets, parsing can be moved away from the main isolate using appropriate background-processing techniques.

import 'dart:convert';
import 'package:flutter/foundation.dart';

List<Post> parsePosts(String responseBody) {
  final List<dynamic> jsonData = jsonDecode(responseBody);

  return jsonData
      .map((json) => Post.fromJson(json))
      .toList();
}

final posts = await compute(parsePosts, response.body);

Background processing can help keep the UI responsive when JSON parsing becomes computationally expensive.

40. Common API Errors

• No internet connection.
• Invalid URL.
• Server is unavailable.
• Request timeout.
• Unauthorized request.
• Forbidden resource.
• Resource not found.
• Invalid request body.
• Invalid JSON response.
• Unexpected API response structure.
• SSL or certificate problems.

41. Better API Error Handling

Future<Post> fetchPost() async {
  try {
    final response = await http.get(
      Uri.parse('https://example.com/api/posts/1'),
    );

    switch (response.statusCode) {
      case 200:
        return Post.fromJson(jsonDecode(response.body));
      case 401:
        throw Exception('Authentication required');
      case 404:
        throw Exception('Post not found');
      case 500:
        throw Exception('Server error');
      default:
        throw Exception(
          'Unexpected status: ${response.statusCode}',
        );
    }
  } catch (e) {
    throw Exception('Unable to fetch post: $e');
  }
}

42. Complete API Integration Example

Post Model

class Post {
  final int id;
  final String title;
  final String body;

  Post({
    required this.id,
    required this.title,
    required this.body,
  });

  factory Post.fromJson(Map<String, dynamic> json) {
    return Post(
      id: json['id'],
      title: json['title'],
      body: json['body'],
    );
  }
}

API Function

Future<Post> fetchPost() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts/1'),
  );

  if (response.statusCode == 200) {
    return Post.fromJson(
      jsonDecode(response.body),
    );
  }

  throw Exception('Failed to load post');
}

Flutter Screen

class PostScreen extends StatefulWidget {
  const PostScreen({super.key});

  @override
  State<PostScreen> createState() => _PostScreenState();
}

class _PostScreenState extends State<PostScreen> {
  late Future<Post> postFuture;

  @override
  void initState() {
    super.initState();
    postFuture = fetchPost();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('API Example'),
      ),
      body: FutureBuilder<Post>(
        future: postFuture,
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const Center(
              child: CircularProgressIndicator(),
            );
          }

          if (snapshot.hasError) {
            return Center(
              child: Text('Error: ${snapshot.error}'),
            );
          }

          if (!snapshot.hasData) {
            return const Center(
              child: Text('No data found'),
            );
          }

          final post = snapshot.data!;

          return Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  post.title,
                  style: const TextStyle(
                    fontSize: 22,
                    fontWeight: FontWeight.bold,
                  ),
                ),
                const SizedBox(height: 12),
                Text(post.body),
              ],
            ),
          );
        },
      ),
    );
  }
}

43. API Architecture Flow

User
  ↓
Flutter UI
  ↓
State Management
  ↓
Repository
  ↓
API Service
  ↓
HTTP Client
  ↓
REST API
  ↓
Backend Server
  ↓
Database
  ↑
JSON Response
  ↑
HTTP Response
  ↑
Model
  ↑
State Management
  ↑
Flutter UI

44. API Best Practices in Flutter

• Use the http package or another appropriate HTTP client.
• Keep API logic outside UI widgets.
• Use model classes for structured API data.
• Use async and await correctly.
• Always handle loading and error states.
• Check HTTP status codes.
• Use timeouts for network operations where appropriate.
• Use authentication headers for protected APIs.
• Never expose private production secrets in client-side code.
• Use repositories or service classes in larger applications.
• Use dependency injection when appropriate.
• Write tests for API services.
• Use HTTPS for secure communication.
• Validate and safely process API responses.
• Provide retry functionality for appropriate temporary failures.

45. API vs Database

46. API vs WebSocket

47. Practical API Project Example

A beginner-friendly Flutter API project can be a Product Management App.

Features

• Fetch products from an API.
• Display products in a GridView or ListView.
• Search products.
• Filter products by category.
• View product details.
• Create a product.
• Update a product.
• Delete a product.
• Display loading indicators.
• Handle network errors.
• Implement pull-to-refresh.

Suggested Structure

lib/
├── models/
│   └── product.dart
├── services/
│   └── product_api_service.dart
├── repositories/
│   └── product_repository.dart
├── screens/
│   ├── product_list_screen.dart
│   └── product_detail_screen.dart
├── widgets/
│   └── product_card.dart
└── main.dart

48. Common Mistakes When Working with APIs

• Calling API requests repeatedly from build().
• Not checking statusCode.
• Not handling network exceptions.
• Assuming every response contains valid JSON.
• Ignoring loading states.
• Ignoring empty responses.
• Hard-coding sensitive credentials.
• Putting all API code inside a widget.
• Not using HTTPS in production.
• Creating unnecessarily complicated API architecture for a small application.
• Not testing failure scenarios.

49. Practice Exercises

1. Create a Flutter application that fetches a single post from an API.
2. Display the post title and body.
3. Fetch a list of posts and display them using ListView.builder.
4. Create a Dart model for the API response.
5. Implement a POST request.
6. Implement PUT and PATCH requests.
7. Implement a DELETE request.
8. Add loading and error states.
9. Add a retry button.
10. Add pull-to-refresh.
11. Add query parameters for searching.
12. Add authentication headers to a protected endpoint.
13. Create a separate API service class.
14. Separate models, services, repositories, and UI.

50. Interview Questions on APIs in Flutter

1. What is an API?
2. What is a REST API?
3. Why are APIs required in Flutter applications?
4. What is the difference between GET and POST?
5. What is the difference between PUT and PATCH?
6. What is the purpose of DELETE?
7. What is JSON?
8. How do you decode JSON in Dart?
9. What is Future in Dart?
10. Why are async and await used for API calls?
11. What is http.Response?
12. What is statusCode?
13. How do you handle API errors?
14. How do you add authentication headers?
15. What is the purpose of Content-Type?
16. Why should API calls not normally be placed directly inside build()?
17. How does FutureBuilder help with API calls?
18. Why should model classes be used?
19. What is an API service class?
20. Why is dependency injection useful for HTTP clients?

51. Quick Revision

52. Official Flutter Resources

• Flutter Networking Documentation
• Flutter Networking Cookbook
• Fetch Data from the Internet
• Send Data to the Internet
• Update Data over the Internet
• Make Authenticated Requests
• Dart HTTP Package

53. Learn Flutter with JustAcademy

To learn Flutter development in a structured way, explore the JustAcademy Flutter Training Course.

You can also register for a demo through the JustAcademy Flutter Course Demo Registration page.

54. Recommended API Development Process

A practical API integration workflow can be organized into the following steps:

1. Understand the API documentation.
2. Identify the required endpoints.
3. Identify HTTP methods and request parameters.
4. Create the required Dart models.
5. Configure the HTTP client.
6. Create API service methods.
7. Add repository or data-layer logic when appropriate.
8. Connect the data layer to state management.
9. Handle loading, success, empty, and error states.
10. Display the data in the Flutter UI.
11. Add authentication and secure request handling when required.
12. Test successful and failed API scenarios.

API Documentation
       ↓
Endpoint Design
       ↓
Dart Models
       ↓
API Service
       ↓
Repository
       ↓
State Management
       ↓
Flutter UI
       ↓
Testing & Error Handling

55. Real-World API Use Cases

56. Learning Outcome

After studying this topic, you should be able to:

• Explain what an API is and why Flutter applications use APIs.
• Understand REST APIs and common HTTP methods.
• Install and use the http package.
• Create GET, POST, PUT, PATCH, and DELETE requests.
• Work with URLs, query parameters, path parameters, and headers.
• Decode JSON responses using Dart.
• Create Dart model classes from API responses.
• Handle asynchronous API operations using Future, async, and await.
• Use FutureBuilder for Future-based UI.
• Handle loading, success, empty, and error states.
• Implement authentication headers.
• Create reusable API service classes.
• Separate models, services, repositories, and UI.
• Handle timeouts, exceptions, retries, and network failures.
• Design a scalable API integration structure for Flutter applications.

57. Summary

APIs are a fundamental part of modern Flutter application development. They allow Flutter applications to communicate with backend servers and external services, retrieve and submit data, authenticate users, and build dynamic data-driven experiences.

To work effectively with APIs in Flutter, developers should understand HTTP methods, URLs, query parameters, headers, JSON, status codes, asynchronous programming, authentication, error handling, models, API services, repositories, and UI state management.

A common API integration flow is:

Flutter UI
   ↓
User Action
   ↓
Service / Repository
   ↓
HTTP Request
   ↓
REST API
   ↓
Backend / Database
   ↓
HTTP Response
   ↓
JSON
   ↓
Dart Model
   ↓
Application State
   ↓
Flutter UI

With these concepts, developers can build Flutter applications that communicate reliably with real-world APIs and backend systems.