name: flutter-networking
description: Comprehensive Flutter networking guidance including HTTP CRUD operations, WebSocket connections, authentication, error handling, and performance optimization. Use when Claude needs to implement HTTP requests GET POST PUT DELETE, WebSocket real-time communication, authenticated requests with headers and tokens, background parsing with isolates, REST API integration with proper error handling, or any network-related functionality in Flutter applications.

Flutter Networking

Quick Start

Add HTTP dependency to pubspec.yaml:

dependencies:
  http: ^1.6.0

Basic GET request:

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

Future<Album> fetchAlbum() async {
  final response = await http.get(
    Uri.parse('https://api.example.com/albums/1'),
  );

  if (response.statusCode == 200) {
    return Album.fromJson(jsonDecode(response.body));
  } else {
    throw Exception('Failed to load album');
  }
}

Use in UI with FutureBuilder:

FutureBuilder<Album>(
  future: futureAlbum,
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return Text(snapshot.data!.title);
    } else if (snapshot.hasError) {
      return Text('${snapshot.error}');
    }
    return const CircularProgressIndicator();
  },
)

HTTP Methods

GET - Fetch Data

Use for retrieving data. See http-basics.md for complete examples.

POST - Create Data

Use for creating new resources. Requires Content-Type: application/json header.

final response = await http.post(
  Uri.parse('https://api.example.com/albums'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

See http-basics.md for POST examples.

PUT - Update Data

Use for updating existing resources.

final response = await http.put(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

DELETE - Remove Data

Use for deleting resources.

final response = await http.delete(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
);

WebSocket

Add WebSocket dependency:

dependencies:
  web_socket_channel: ^3.0.3

Basic WebSocket connection:

import 'package:web_socket_channel/web_socket_channel.dart';

final _channel = WebSocketChannel.connect(
  Uri.parse('wss://echo.websocket.events'),
);

// Listen for messages
StreamBuilder(
  stream: _channel.stream,
  builder: (context, snapshot) {
    return Text(snapshot.hasData ? '${snapshot.data}' : '');
  },
)

// Send message
_channel.sink.add('Hello');

// Close connection
_channel.sink.close();

See websockets.md for complete WebSocket implementation.

Authentication

Add authorization headers to requests:

import 'dart:io';

final response = await http.get(
  Uri.parse('https://api.example.com/data'),
  headers: {HttpHeaders.authorizationHeader: 'Bearer $token'},
);

Common authentication patterns:
- Bearer Token: Authorization: Bearer <token>
- Basic Auth: Authorization: Basic <base64_credentials>
- API Key: X-API-Key: <key>

See authentication.md for detailed authentication strategies.

Error Handling

Handle HTTP errors appropriately:

if (response.statusCode >= 200 && response.statusCode < 300) {
  return Data.fromJson(jsonDecode(response.body));
} else if (response.statusCode == 401) {
  throw UnauthorizedException();
} else if (response.statusCode == 404) {
  throw NotFoundException();
} else {
  throw ServerException();
}

See error-handling.md for comprehensive error handling strategies.

Performance

Background Parsing with Isolates

For large JSON responses, use compute() to parse in background isolate:

import 'package:flutter/foundation.dart';

Future<List<Photo>> fetchPhotos(http.Client client) async {
  final response = await client.get(
    Uri.parse('https://api.example.com/photos'),
  );

  return compute(parsePhotos, response.body);
}

List<Photo> parsePhotos(String responseBody) {
  final parsed = (jsonDecode(responseBody) as List)
      .cast<Map<String, dynamic>>();
  return parsed.map<Photo>((json) => Photo.fromJson(json)).toList();
}

See performance.md for optimization techniques.

Integration with Architecture

When using MVVM architecture (see flutter-architecture):

1. Service Layer: Create HTTP service for API endpoints
2. Repository Layer: Aggregate data from services, handle caching
3. ViewModel Layer: Transform repository data for UI

Example service:

class AlbumService {
  final http.Client _client;

  AlbumService(this._client);

  Future<Album> fetchAlbum(int id) async {
    final response = await _client.get(
      Uri.parse('https://api.example.com/albums/$id'),
    );

    if (response.statusCode == 200) {
      return Album.fromJson(jsonDecode(response.body));
    } else {
      throw Exception('Failed to load album');
    }
  }
}

Common Patterns

Repository Pattern

Single source of truth for data type:

class AlbumRepository {
  final AlbumService _service;
  final LocalStorage _cache;

  Future<Album> getAlbum(int id) async {
    try {
      return await _cache.getAlbum(id) ?? 
             await _service.fetchAlbum(id);
    } catch (e) {
      throw AlbumFetchException();
    }
  }
}

Retry Logic

Implement exponential backoff for failed requests:

Future<T> fetchWithRetry<T>(
  Future<T> Function() fetch, {
  int maxRetries = 3,
}) async {
  for (int i = 0; i < maxRetries; i++) {
    try {
      return await fetch();
    } catch (e) {
      if (i == maxRetries - 1) rethrow;
      await Future.delayed(Duration(seconds: 2 << i));
    }
  }
  throw StateError('Unreachable');
}

Best Practices

DO

• Use type-safe model classes with fromJson factories
• Handle all HTTP status codes appropriately
• Parse JSON in background isolates for large responses
• Implement retry logic for transient failures
• Cache responses when appropriate
• Use proper timeouts
• Secure tokens and credentials

DON'T

• Parse JSON on main thread for large responses
• Ignore error states in UI
• Store tokens in source code or public repositories
• Make requests without timeout configuration
• Block UI thread with network operations
• Throw generic exceptions without context

Resources

references/

• http-basics.md - Complete HTTP CRUD operations examples
• websockets.md - WebSocket implementation patterns
• authentication.md - Authentication strategies and token management
• error-handling.md - Comprehensive error handling patterns
• performance.md - Optimization techniques and best practices

assets/examples/

• fetch_example.dart - Complete GET request with FutureBuilder
• post_example.dart - POST request implementation
• websocket_example.dart - WebSocket client with stream handling
• auth_example.dart - Authenticated request example
• background_parsing.dart - compute() for JSON parsing

assets/code-templates/

• http_service.dart - Reusable HTTP service template
• repository_template.dart - Repository pattern template