JSON and REST adapters
FdcJsonAdapter defines a backend request and response contract while leaving transport entirely under application control. FdcRestAdapter builds on that contract and adds HTTP request modeling without forcing a specific networking package.
JSON adapter
final adapter = FdcJsonAdapter(
source: 'customers',
onOpen: (event) async {
final response = await backend.loadCustomers(event.toMap());
return response;
},
onApply: (event) async {
return backend.applyCustomerChanges(event.toMap());
},
);
The application receives structured events and can forward toMap() or toJson() to any backend transport.
A successful open response uses the canonical envelope:
{
"source": "customers",
"rows": [
{"customer_id": 1, "company": "Northstar Trading", "city": "Boston"}
],
"totalCount": 1
}
When includeTotalCount is requested, totalCount is required.
Read-only and writable modes
A JSON adapter without onApply is read-only. Supplying onApply makes the adapter writable.
Apply events contain ordered delete, update, and insert actions. Backend responses can return server-authoritative values, such as generated keys or normalized values, correlated back to local rows by recordId.
Aggregates
Configure onAggregate when the backend can calculate aggregates over the complete filtered result set:
FdcJsonAdapter(
source: 'orders',
onOpen: loadOrders,
onAggregate: loadOrderAggregates,
)
Aggregate requests intentionally do not include page limits.
Metadata and timeouts
FdcJsonAdapter(
source: 'orders',
openTimeout: const Duration(seconds: 30),
applyTimeout: const Duration(seconds: 20),
metaBuilder: (operation) => {
'tenant': currentTenantId,
'requestId': createRequestId(),
},
onOpen: loadOrders,
onApply: applyOrders,
)
Duration.zero disables the corresponding timeout.
REST adapter
FdcRestAdapter converts the canonical JSON operations into transport-neutral HTTP requests:
final adapter = FdcRestAdapter(
source: 'customers',
baseUri: Uri.parse('https://api.example.com/data'),
onSend: sendRequest,
);
By default, requests are sent as JSON POST operations to source-specific open, apply, and, when enabled, aggregate endpoints.
The onSend callback receives FdcRestRequest, so the application can use package:http, Dio, generated clients, custom interceptors, or test fakes.
Headers, endpoint URI construction, HTTP methods, and payload placement are configurable without changing dataset code.