Skip to main content

JSON and REST Adapters

PRO
Pro preview

These adapters are part of FD Components Pro, which is documented as a preview and is not publicly available yet. See Editions and Availability.

FDC provides two remote adapter entry points over one canonical backend contract:

AdapterUse it when
FdcJsonAdapterThe application owns transport, already has a service/client layer, or communicates through something other than modeled HTTP requests.
FdcRestAdapterThe backend is reached through HTTP and the application wants FDC to model endpoints, methods, headers, payload placement, and status handling.

Both adapters use the same JSON Contract for open, apply, and aggregate operations.

Relationship between the adapters​

FdcRestAdapter extends FdcJsonAdapter. It does not introduce a second data protocol.

FdcRestAdapter
  HTTP URI, method, headers, payload and status handling
        ↓
FdcJsonAdapter
  request/response envelopes, materialization and apply semantics
        ↓
FdcDataSet
  fields, records, editing, validation and change tracking

The JSON layer remains responsible for:

  • serializing effective query state;
  • validating response envelopes;
  • typed field materialization;
  • correlating apply values by recordId;
  • parsing aggregates;
  • timeouts and adapter capabilities.

The REST layer adds:

  • default and custom endpoint URIs;
  • HTTP methods and payload placement;
  • normalized request headers;
  • an application-owned onSend transport callback;
  • conversion of non-2xx responses into adapter exceptions.

Choose JSON when transport is already solved​

FdcJsonAdapter(
  source: 'customers',
  onOpen: (event) => customerClient.query(event.toMap()),
  onApply: (event) => customerClient.apply(event.toMap()),
)

The callback can call an HTTP SDK, WebSocket client, desktop IPC bridge, test fake, or any other application service.

Choose REST for modeled HTTP requests​

FdcRestAdapter(
  source: 'customers',
  baseUri: Uri.parse('https://api.example.com/fdc'),
  headersBuilder: (_) async => <String, String>{
    'authorization': 'Bearer ${await tokenProvider.token()}',
  },
  onSend: sendFdcRequest,
)

The application still selects the concrete HTTP package, while the adapter supplies a stable FdcRestRequest and consumes an FdcRestResponse.

Documentation map​

  • JSON Adapter — callbacks, capabilities, metadata, timeouts, type materialization, apply and aggregate integration.
  • REST Adapter — endpoints, onSend, headers, methods, payload placement, HTTP errors and transport testing.
  • JSON Contract — exact request and response properties for open, apply and aggregate operations.
  • Server-Side Operations — backend semantics for filtering, sorting, search, paging, counts and aggregates.