Concorde documentation — Fetching remote data in Concorde. Hub for loading online data: @get decorator, Endpoint, API configuration, dynamic paths, sonic-list fetch, sonic-queue, legacy sonic-fetch. Doc ID: hubs/remote-data. Keywords: @get, fetch, remote data, API, Endpoint, ApiResult, serviceURL, sonic-list, sonic-queue, HTTP GET. URL: https://concorde.supersoniks.org/crawl/hubs/remote-data.html.

Fetch

> New apps: prefer @get for a typed GET on a component, or List / Queue with fetch for collections. Use Local API demos (serviceURL="/docs-mock-api") to try examples offline.

The sonic-fetch component requests and stores API data. It extends the Fetcher and Subscriber mixins.

Basic usage
In order to work properly the  sonic-fetch  component needs at least the following attributes.
- serviceURL : A base service url. This attribute can be inherited from an ancestor.
  ex : /docs-mock-api
- endPoint : the specific location where requests for information are sent (see the api docs).
  ex : api/users | api/users?page=2 | api/users/2
- dataProvider (Required) : An ID that is used as a reference to the object storing the data returned by the API.
This attribute can be inherited from an ancestor.

     Hover to see the data

DataProvider as an endPoint
If no endPoint is specified it will be filled by the dataProvider ID instead

     Hover to see the data

HeadersDataProvider

 Deprecated

Key
When the key attribute is present, only a sub-part of the data received is injected into the dataProvider.
We can use the dot syntax to target what we want to keep.

For example if the data 

List

> Try offline: serviceURL="/docs-mock-api" and dataProvider="api/users" with key="data" — see Local API demos. Recommended patterns: Data flow.

The sonic-list component renders one row per entry in props (array from fetch or set on the element).

List extends Subscriber and Fetcher:
 Subscriber — props + dataProvider
 Fetcher — optional fetch + serviceURL / key (see Fetch)

Row renderer (items) — recommended

From a Lit parent, pass a function on the items property (ListItems). Each row is wrapped in a sonic-subscriber with dataProvider="…/list-item/n" (hover rows with debug).

private items = ({ firstname, lastname, email, avatar }) => html

   ${firstname}  ${lastname}
   ${email}
;

html  ;

Use .items=${fn} (property binding): Lit passes functions only as properties, not as HTML attributes — @property({ type: Function }) does not change that. Same for .noItems, .separator, .skeleton. The callback receives each row object (replacing data-bind /   in a  ).

Live demo + TypeScript source (one file, no Markdown copy):

Implementation: src/docs/example/docs-users-list.ts — row markup in the items callback (item.firstname, …), same idea as replacing data-bind /   in a  .

Alte

Queue

> Try offline: serviceURL="/docs-mock-api" — see Local API demos. Row rendering: Data flow (.items property binding).

sonic-queue loads data in batches. Each batch is an internal List with its own dataProvider (…/list-item/0, …/1, …).

| Mechanism | Role |
|-----------|------|
| dataProviderExpression | API path template; $offset and $limit are replaced per batch |
| lazyload | Load the next batch when the user scrolls near the end |
| dataFilterProvider | Publisher id of a form (formDataProvider); field values are merged into the request query string |
| filteredFields | Optional list of form field names to exclude from the query (space-separated) — omit when every field should be sent |
| .items, .noItems, .separator, .skeleton | Lit callbacks forwarded to each batch list (use the dot — functions are properties, not attributes) |

Lazy load — $offset and $limit

When the expression contains $offset and $limit, the queue:

1. Fetches the first batch with offset=0 (or the initial offset attribute) and perpage=$limit.
2. On scroll, appends a batch with offset increased by the previous batch size.
3. Stops when a batch returns fewer rows than limit (or none).

The doc mock im

Data flow

Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store (legacy Publisher API: Legacy: Sharing data).

Quick map

| Need | Use |
|------|-----|
| Read/write in code | get / set / dp + DataProviderKey (static paths only) |
| Reactive Lit template | sub(key) or @subscribe |
| Read component state from store | @subscribe + DataProviderKey  + @state |
| Inherit ancestor attributes | @ancestorAttribute |
| Write from component state | @publish |
| React to assignments | @handle |
| HTTP GET | @get + Endpoint, or sonic-list / sonic-queue with fetch |
| HTTP POST (body from store) | @post + Endpoint + body DataProviderKey |
| HTTP PUT / PATCH (body from store) | @put / @patch — same model as @post |
| Forms | formDataProvider + name on fields |
| Offline doc demos | serviceURL="/docs-mock-api" — Local API demos |

Skill: concorde-get-set-dp in the package ai/ folder.

DataProviderKey

import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
import { dp, get, set } from "@supersoniks/concorde/utils";

const cartKey = new DataProviderKey<{ items: string[] }>("cart");

set(cartKey, { items: [] });
dp(c

@get

Loads data through API.getDetailed. The decorated property is ApiResult  | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.

Pass an Endpoint  as the first argument. Import get and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.

Configuration

- Default: HTML.getApiConfiguration(host) (ancestor serviceURL, etc.).
- Second argument: DataProviderKey  — config is read from the publisher at the resolved path; internal mutations trigger another GET. See API configuration for mock demos.

Dynamic path

${prop} on the endpoint or config key is resolved on the host. While a placeholder is null or undefined, no GET runs. Optional skipEmptyPlaceholder: true also blocks "" (empty string only). Details: Dynamic path placeholders.

Options (GetOptions)

Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:

| Option | Description |
|--------|-------------|
| skipEmptyPlaceholder | Treat "" as not ready (see Dynamic path). |
| refetchEveryMs | Automatic polling interval (ms). 0 or omitted = no polling. |
| tri

@patch

Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).

Pass an Endpoint  and a DataProviderKey for the request body. Import patch and ApiResult from @supersoniks/concorde/decorators.

Configuration

Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.

Options (PatchOptions)

Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.

Import

import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";

Example

const patchBodyKey = new DataProviderKey<Partial<Resource>>("resourcePatch");

@patch(
  new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"),
  patchBodyKey,
  { skipEmptyPlaceholder: true },
)
@state()
payload?: ApiResult<Resource> | null;

See also

- @post — POST (live demos)
- @put — full rep

@post

Sends data through API.postDetailed. The decorated property is ApiResult  | null: request, response, and typed result.

Pass an Endpoint  as the first argument and a DataProviderKey for the request body as the second. Import post and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.

Configuration

Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey  as third argument. See API configuration for mock demos.

Optional PostOptions (third or fourth argument)

| Option | Description |
|--------|-------------|
| refetchEveryMs | Re-post on an interval (ms). |
| skipIfBodyMissing | Skip when body publisher is null/undefined (default: true). |
| autoPostOnBodyMutation | Re-post when the body publisher mutates (default: true). false = manual via triggerKey.invalidate(). |
| skipEmptyPlaceholder | If true, a placeholder resolved to '' blocks the request (empty string only — not 0 or false). See Dynamic paths. |
| triggerKey | DataProviderKey — invalidate() re-runs the POST with the current body. |

When the POST runs again

- Body publisher onInternalMutation when autoPostOnBodyMutation is true (defa

@put

Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).

Pass an Endpoint  and a DataProviderKey for the request body. Import put and ApiResult from @supersoniks/concorde/decorators.

Configuration

Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.

Options (PutOptions)

Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.

Import

import { put, type ApiResult } from "@supersoniks/concorde/decorators";
import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";

Example

const bodyKey = new DataProviderKey<UpdatePayload>("resourceBody");

@put(new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"), bodyKey)
@state()
payload?: ApiResult<Resource> | null;

Changing resourceId on the host re-runs the PUT when the path becomes ready — see Dynamic path placeholders.

See also

- @post —

API configuration

APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, sonic-submit, the wording() directive, @get, @post, @put, and @patch.

> Mock service: same Local API demos Service Worker / Vite middleware. Routes used on this page are listed in the API config routes section below.

Attribute map

| Attribute (ancestor) | APIConfiguration field | Role |
|---------------------|---------------------------|------|
| serviceURL | serviceURL | Base URL (e.g. /docs-mock-api) |
| token | token | Static Bearer sent on REST calls |
| userName / password | userName / password | Basic auth for tokenProvider fetch only |
| eventsApiToken | authToken | Bearer for tokenProvider when no Basic |
| tokenProvider | tokenProvider | Path to GET a new token ({ token } JSON) |
| wordingProvider | — (read by wording()) | Base path + query for label batch GET |
| wordingVersionProvider | — | Publisher id; bump version → reload wordings |
| credentials | credentials | fetch credentials mode |
| addHTTPResponse | addHTTPResponse | Attach sonichttpresponse 

Dynamic path placeholders

Decorators and DataProviderKey paths can include placeholders resolved on the host component at runtime:

- ${prop} or {$prop} — e.g. "users/${userId}", "api/sessions/${sessionId}/sync"
- Nested expressions — e.g. "teams.${teamId}.members"

Resolution is done by resolveDynamicPath. The root property names (userId, sessionId, …) are watched via requestAnimationFrame (see dynamicPropertyWatch.ts).

Default behaviour (ready / not ready)

| Placeholder value | Path ready? | Inserted segment | Notes |
|-------------------|---------------|------------------|-------|
| undefined | no | — | Wait until defined |
| null | no | — | Same as undefined |
| "" | yes | empty string | e.g. sessions//sync — request may still run |
| 0 | yes | "0" | Not treated as “missing” |
| false | yes | "false" | |
| 42, "alpha" | yes | "42", "alpha" | |

When ready: false, decorators do not call the network (for @get / @post / @put / @patch), unsubscribe (@bind / @subscribe), or skip publisher binding (@publish / @handle). The decorated property is often left unchanged or set to undefined (HTTP decorators).

When the placeholder later becomes valid, observers run again and behaviour r

Endpoint

Endpoint  describes a single HTTP path (or a path accepted by API.get) and carries the expected response type T. Unlike DataProviderKey, there is no dot-navigation: the path is one string.

The optional second generic U (default any) describes host properties used to resolve dynamic segments in the path (${…} / {$…}), for example with @get or @post. See Dynamic path placeholders for null / undefined / "" / 0 and skipEmptyPlaceholder.

Import

import { Endpoint } from "@supersoniks/concorde/utils/endpoint";

Construction

const users = new Endpoint<User[]>("users?limit=10");
users.path; // "users?limit=10"

const one = new Endpoint<User, { userId: string }>("users/${userId}");
// userId on the host class is observed when used with @get

Normalization

Endpoint.normalizePath trims the string, rejects an empty path, strips leading slashes for paths relative to serviceURL, collapses duplicate slashes, and validates absolute http(s):// URLs.

Publisher key for payloads

getDataProviderKey() returns a typed publisher key whose path matches the endpoint path (payload typing follows ApiResult for this endpoint). Useful when pairing @get with @publish / @subscribe (see