Skip to content

Configuration

The client

final client = PlayxNetworkClient(
  dio: Dio(BaseOptions(baseUrl: 'https://api.example.com/')),
  customHeaders: () async => {'authorization': 'Bearer $token'},
  customQuery: () => {'lang': 'en'},
  customPathParameters: () => {'version': 'v2'},
  onUnauthorizedRequestReceived: (response) => signOut(),
  errorMapper: (json) => json['message'] as String?,
  errorExtraMapper: ApiError.fromJson,
  hasInternetConnection: checkConnectivity,
  settings: const PlayxNetworkClientSettings(),
);
Parameter Type
dio Dio Required. The Dio instance that sends the requests. Configure the base URL and the timeouts here.
customHeaders FutureOr<Map<String, dynamic>> Function()? Headers added to every request. More
customQuery FutureOr<Map<String, dynamic>> Function()? Query parameters added to every request.
customPathParameters FutureOr<Map<String, dynamic>> Function()? Values for {placeholders} in every path. More
onUnauthorizedRequestReceived void Function(Response?)? Called for the unauthorized status codes. More
errorMapper String? Function(dynamic)? Turns an error body into the server's message. Defaults to a parser for the common shapes. More
errorExtraMapper Object? Function(dynamic)? Turns an error body into your own error object. More
hasInternetConnection FutureOr<bool> Function()? Tells "offline" from "server unreachable". More
settings PlayxNetworkClientSettings See below.

One client

Create one client for each backend and reuse it. It keeps the Dio instance, the interceptors and the cancellation tags.

Settings

PlayxNetworkClientSettings groups the options. Every request accepts a settings: argument that replaces the client's settings for that request.

const PlayxNetworkClientSettings(
  shouldShowApiErrors: true,
  successRequestCodes: [200, 201],
  unauthorizedRequestCodes: [401, 403],
  treatEmptyResponseAsSuccess: false,
  useIsolateForMappingJson: true,
  useWorkMangerForMappingJsonInIsolate: true,
  exceptionMessages: DefaultEnglishExceptionMessage(),
  logSettings: PlayxNetworkLoggerSettings(),
);
Setting Default
shouldShowApiErrors true Whether error.message is the server's message (true) or always the generic one (false).
successRequestCodes [200, 201] Status codes that are a success. A 400 is always an error. Add 204 if your API uses it. More
unauthorizedRequestCodes [401, 403] Codes that produce UnauthorizedRequestException and call onUnauthorizedRequestReceived.
treatEmptyResponseAsSuccess false Return [] instead of EmptyResponseException for empty list responses. More
useIsolateForMappingJson true Run fromJson in an isolate. More
useWorkMangerForMappingJsonInIsolate true Use work_manager for that isolate instead of compute.
exceptionMessages English The generic error texts. More
logSettings PlayxNetworkLoggerSettings() What is logged. More

settings.copyWith(...) returns a changed copy, which is handy for per-request overrides:

final quiet = client.settings.copyWith(shouldShowApiErrors: false);
await client.get<User>('me', fromJson: User.fromJson, settings: quiet);

Default Dio

PlayxNetworkClient.createDefaultDioClient(baseUrl: ...) returns a Dio that accepts every status code (so the library decides what is an error), follows redirects and has a 30 second connect timeout.

final client = PlayxNetworkClient(
  dio: PlayxNetworkClient.createDefaultDioClient(baseUrl: 'https://api.example.com/'),
);