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.