Integrating Backend Services: RESTful APIs and GraphQL in Flutter

Every Flutter app that displays dynamic data needs to communicate with a backend server. The two dominant paradigms—RESTful APIs and GraphQL—solve the data-fetching problem differently, and choosing the right one (or combining both) depends on your data shape, team expertise, and performance requirements. REST uses multiple endpoints with fixed response structures. GraphQL uses a single endpoint where the client specifies exactly what data it needs. Understanding the trade-offs is essential before writing your first API call.

Flutter's official `http` package provides lightweight HTTP networking. Make a GET request: `final response = await http.get(Uri.parse('https://api.example.com/users'));`. Parse the JSON response: `final users = jsonDecode(response.body) as List;`. For POST requests, include headers and body: `await http.post(uri, headers: {'Content-Type': 'application/json'}, body: jsonEncode({'name': 'John'}))`. Always check `response.statusCode` before parsing—200 for success, 401 for unauthorized, 404 for not found, 500 for server error. The `http` package is ideal for simple apps with a few API calls and no advanced requirements.

Dio is the most popular HTTP client in the Flutter ecosystem, offering features the `http` package lacks. Interceptors enable global request/response processing: add authentication headers to every request, log all API calls, or implement automatic token refresh when a 401 is received. Request cancellation with `CancelToken` prevents wasted bandwidth when users navigate away. Retry logic with `dio_smart_retry` automatically retries failed requests with exponential backoff. Form data and file uploads work natively: `FormData.fromMap({'file': await MultipartFile.fromFile(path)})`. Configure base URLs, timeouts, and default headers in a single `Dio()` instance shared across the app.

The `graphql_flutter` package provides a full-featured GraphQL client for Flutter. Configure the client: `GraphQLClient(link: HttpLink('https://api.example.com/graphql'), cache: GraphQLCache())`. Use the `Query` widget for declarative data fetching: `Query(options: QueryOptions(document: gql('{users { id name email }}'))`, builder: (result, {refetch, fetchMore}) { ... })`. The key advantage: request exactly the fields you need—no over-fetching (receiving unnecessary data) or under-fetching (needing multiple requests). This reduces payload sizes by 30–70% compared to REST for complex data graphs.

Mutations modify server-side data: `Mutation(options: MutationOptions(document: gql('mutation CreateUser($name: String!) { createUser(name: $name) { id name } }'))`. Subscriptions enable real-time data streams via WebSocket: `Subscription(options: SubscriptionOptions(document: gql('subscription { messageAdded { id text sender } }')))`. Configure the WebSocket link: `WebSocketLink('wss://api.example.com/graphql')`. Combine HTTP and WebSocket links using `Link.split()` to route subscriptions through WebSocket and queries/mutations through HTTP. This enables chat apps, live dashboards, and collaborative editing features.

Both REST and GraphQL benefit from client-side caching. GraphQL's `GraphQLCache` with `InMemoryStore` provides normalized caching—each entity is stored once by its ID, and any query referencing that entity receives the cached version automatically. For REST, use packages like `dio_cache_interceptor` or implement manual caching with `Hive` or `shared_preferences`. The cache-first policy shows cached data immediately and fetches updates in the background. The network-only policy always fetches fresh data. Choose policies per query based on data freshness requirements.

Robust error handling separates amateur from production-quality apps. Create a centralized error handler that categorizes failures: network errors (no connectivity—show cached data or offline UI), timeout errors (slow server—retry with backoff), authentication errors (expired token—refresh and retry), validation errors (invalid input—show field-level messages), and server errors (500—show generic error with retry). Use `connectivity_plus` to detect network state and proactively disable API-dependent features when offline. For GraphQL, handle both `graphQLErrors` (schema validation, authorization) and `linkException` (network) separately.

The Repository Pattern creates a clean abstraction between your Flutter UI and the data source. Define a `UserRepository` interface with methods like `Future> getUsers()` and `Future createUser(String name)`. Create `RestUserRepository` and `GraphqlUserRepository` implementations. Inject the repository into your state management layer (Riverpod, BLoC, Provider). This enables switching between REST and GraphQL without changing any UI code, facilitates testing with mock repositories, and keeps business logic completely isolated from networking details.