Backend API Calls

Call client.get(uri) or client.post(uri, headers: {'Content-Type': 'application/json'}, body: jsonEncode(data)) on one long-lived http.Client and check response.statusCode. The top-level http.get creates and closes a new Client for every call, losing persistent connections.

connectivity_plus reports which network interfaces are up (wifi, mobile, none), not whether packets reach your server. Captive portals, dead DNS or a down backend all look connected, so treat it as a hint and let the real request decide.

Give the model class a factory fromJson(Map<String, dynamic>) that casts each key into a typed final field, and a toJson() that builds the map back. Raw maps push every typo and type mismatch to runtime, far from the API call.

Call WebSocketChannel.connect(uri), await channel.ready, listen to channel.stream for incoming messages and call channel.sink.add to send. In the State's dispose, cancel the subscription and call channel.sink.close().

A Query widget watches its query, so it uses the watchQuery default, FetchPolicy.cacheAndNetwork; a one-shot client.query defaults to cacheFirst, and mutations and subscriptions to networkOnly. Override per operation in the options or per client with DefaultPolicies.

Add an Interceptor whose onRequest sets options.headers['Authorization'] and then calls handler.next(options). Every callback must call exactly one of next, resolve or reject on its handler, or the request never completes.

Annotate each class with @JsonSerializable(fieldRename: FieldRename.snake, explicitToJson: true), give absent keys nullable types or @JsonKey(defaultValue:), use @JsonKey(name:) for odd keys, and set includeIfNull: false to omit nulls from toJson.

A WebSocketChannel cannot be reopened, so a repository creates a new one per attempt, detects drops via onDone or errors, retries with capped, jittered backoff, closes on backgrounding and reconnects on return, then resubscribes and fetches a snapshot.

Split subscriptions to a WebSocketLink with Link.split((r) => r.isSubscription, wsLink, httpChain), match subProtocol to the server (the default is the old graphql-ws protocol), send auth in SocketClientConfig.initialPayload, and render with the Subscription widget or useSubscription.

Pass a parserFn to QueryOptions<TParsed> and read result.parsedData, which parses once and caches. graphql_codegen, the generator the package points to, emits typed options, variables and hooks from .graphql files, removing hand-written parsing.

Pass a CancelToken to requests and call cancel() to abort them; each throws a DioException of type cancel. A cancelled token stays cancelled, so any later request using it fails immediately; create a new token per screen or search.

BaseOptions set defaults for every request of one Dio: baseUrl, connectTimeout, sendTimeout, receiveTimeout (null means no limit) and validateStatus, which by default accepts only 2xx. Failures throw DioException with a type such as connectionTimeout, badResponse, cancel or connectionError.

Keep the last successfully parsed response and its fetch time, and on a failed refresh show that data marked stale with a non-blocking error and retry. Only a failure with nothing cached gets a full-screen error.

RetryClient retries 3 times by default, only when the response status is 503; thrown errors such as a dropped connection are not retried. Delays are 500 ms growing 1.5x with no jitter, and it retries any HTTP method.

Set @JsonSerializable(genericArgumentFactories: true) on Page<T>; the generated fromJson then takes a T Function(Object? json) fromJsonT and toJson takes an Object? Function(T value) toJsonT, which the caller supplies, for example Order.fromJson.

@JsonKey(fromJson:, toJson:) suits a one-off field and takes static or top-level functions. A JsonConverter<T, S> is reusable: annotate a field, a whole class or JsonSerializable(converters:), and it also converts T inside collections.

Call channel.sink.close(code, reason), where the code must be 1000 or 3000-4999 and the reason at most 123 UTF-8 bytes. After the stream's onDone, channel.closeCode and channel.closeReason hold what the server sent; both are null before that.

pingInterval makes the dart:io socket ping at that interval and close the connection when no pong arrives in time; it defaults to null, no pings. It is io-only because the portable connect must also run on the web.

connect returns before the handshake; channel.ready completes when the socket is open or with an error if it failed. A failure also reaches channel.stream as a WebSocketChannelException followed by done, so both must be handled.

The cache merges changed fields of entities it already holds, but it cannot know a new review belongs in a cached list. Add it in MutationOptions.update with cache.readQuery and cache.writeQuery, or refetch the list query.

Use a QueuedInterceptor so onError handles one 401 at a time. The first refreshes through a plain Dio without that interceptor; later ones see the token already changed. Each replays on the plain Dio and resolves its handler.

Override Interceptor.onError: skip non-idempotent methods, cancels and 4xx; retry connection errors, timeouts and 502-504 by waiting a random delay under a capped exponential bound, then resolving with dio.fetch(requestOptions), counting attempts in requestOptions.extra.

Put jsonDecode and the fromJson mapping into one top-level function that takes the response body String, and run it with compute() or Isolate.run. Decoding alone off-isolate is not enough if fromJson still runs on the UI isolate.

Declare a sealed freezed class with one factory constructor per variant, set @Freezed(unionKey: 'type'), map values with unionValueCase or @FreezedUnionValue, and name a catch-all with fallbackUnion, because an unknown value otherwise throws CheckedFromJsonException.

The default IOClient uses dart:io sockets; cupertino_http (URLSession) and cronet_http (Cronet) use the platform stack, gaining VPN and proxy support, HTTP/3 and platform caching. Both implement http.Client, so a factory picks one per platform and call sites stay unchanged.