Build Robust Flutter API Services

Provides expert guidance for designing and implementing robust API services for Flutter applications - HTTP client configuration, error handling, authentication, caching, and API architecture patterns. Core principles: separation of concerns (API logic kept out of UI components), comprehensive error handling with user-friendly messages, strongly typed models with proper serialization, scalable and testable service structure, and performance via caching/connection pooling/request optimization.

Use this skill when setting up an HTTP client for a Flutter app, designing a service-layer architecture around API calls, implementing authentication with token refresh, wiring a repository pattern with caching, or writing tests for API-dependent code.

HTTP client setup wraps Dio in a singleton ApiClient configured with baseUrl, connect/receive timeouts, JSON headers, a LogInterceptor for request/response logging, and an auth interceptor that attaches a bearer token from TokenManager and routes 401 responses into a token-refresh handler.

The service architecture pattern centers on an abstract BaseApiService with a generic handleRequest<T> method that wraps a Dio call, deserializes the response via a fromJson callback, and normalizes errors into a typed ApiResponse<T> (success/error factory constructors carrying data, message, status code, and a success flag) - distinguishing connection timeouts, bad responses (surfacing the server's own error message), and generic network errors. A concrete UserApiService example implements getUser, paginated getUsers with optional search, createUser, and deleteUser, all routed through the shared handleRequest wrapper.

The repository pattern layers caching on top of the API service: UserRepository checks a UserCacheService first (unless forceRefresh is set), falls back to the API service on a cache miss, writes successful API responses back into the cache, and returns a Result<User> success/failure type to callers.

Authentication handling is shown via a dedicated AuthInterceptor that attaches the current access token to every request and, on a 401, attempts a token refresh through AuthManager, retries the original request with the new token, and logs the user out if the refresh itself fails.

Ten best practices: use the correct HTTP method per operation (GET/POST/PUT-PATCH/DELETE), implement request cancellation with CancelToken for long-running calls, add exponential-backoff retry logic, use connection pooling and keep-alive, implement caching with proper invalidation, handle offline scenarios with local storage fallbacks, use request/response transformers for data preprocessing, deduplicate in-flight requests, add logging/monitoring, and use environment-specific configurations per API endpoint.

Testing strategy mocks the API service layer (MockUserApiService extends Mock implements UserApiService) so repository logic can be tested in isolation, with a worked example verifying that UserRepository.getUser correctly surfaces data from a mocked successful API response.

Built on the Dio HTTP client for Flutter/Dart, with its interceptor system for logging and auth, and a repository-pattern architecture pairing an API service layer with a local cache service.

Flutter developers building the API layer of an app who need a testable, well-separated architecture for HTTP calls, error handling, token-refresh authentication, and caching rather than scattering Dio calls directly inside widgets.