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

@get loads data and stores the result in an optional ApiResult  property.
The property is undefined until a result is available.

- payload.result: typed data;
- payload.response: the HTTP response;
- payload.request: the request that was sent.

Minimal usage

const usersEndpoint = new Endpoint ("users");

@get(usersEndpoint)
@state()
payload?: ApiResult ;

The same decorator adapts to a method. The method receives the complete
ApiResult  payload after each GET:

@get(usersEndpoint)
handleUsers(payload?: ApiResult ) {
  if (!payload) return;

  console.log(payload.response?.status);
  console.log(payload.result);
}

The first argument is always an
Endpoint . API configuration is read
from the HTML scope (serviceURL, token, etc.), so the component is usually
placed below an element that provides this configuration.

Refetching a GET

From the component

Keep the decorator in a constant to access refetch(component). Refetch only
targets the instance passed as the argument, even before it has received a
result.

const usersGet = get(new Endpoint ("users"));

@usersGet
@state()
payload?: ApiResult ;

async refresh() {
  const payload = await usersGet.refetch(this);
  console.log(

@patch

@patch applies a partial update with the body from a publisher. It uses the
same model as @post:
Endpoint , DataProviderKey , ApiResult , options, and the
send(component) handle.

Minimal usage

const bodyKey = new DataProviderKey >("users.patch");
const patchUser = patch(new Endpoint ("users/42"), bodyKey);

@patchUser
@state()
payload?: ApiResult ;

The same decorator adapts to a method:

@patch(new Endpoint ("users/42"), bodyKey)
handlePatch(payload?: ApiResult ) {
  if (payload?.response?.ok) console.log(payload.result);
}

To run the operation again from the component:

async savePatch() {
  await patchUser.send(this);
}

send(component) returns a Promise resolved after the PATCH completes. See
@post for the method-decorator form and the
when: "before" option.

The PATCH is also sent automatically when the body mutates, unless
autoPostOnBodyMutation: false is set. The available options are described in
@post:

- autoPostOnBodyMutation
- skipIfBodyMissing
- refetchEveryMs
- skipEmptyPlaceholder
- triggerKey

Pass explicit API configuration as the third argument:

@patch(endpoint, bodyKey, apiConfigurationKey)

Import

import { patch, type ApiResult } from "@supersoniks/

@post

@post sends the contents of a publisher and stores the response in an
optional ApiResult  property. The property is undefined until a result
is available.

Minimal usage

Pass an Endpoint  and a DataProviderKey  for the request body.

const userBodyKey = new DataProviderKey ("users.form");
const createUser = post(new Endpoint ("users"), userBodyKey);

@createUser
@state()
payload?: ApiResult ;

The same decorator adapts to a method and receives the complete payload:

@post(new Endpoint ("users"), userBodyKey)
handleCreate(payload?: ApiResult ) {
  if (payload?.response?.ok) console.log(payload.result);
}

The current body is read from userBodyKey. By default, the POST is sent when
the component connects and after each body mutation. Mutations in the same
frame are coalesced into one request.

API configuration is read from the HTML scope, as with
@get.

Sending the POST again

From the component

Keep the decorator to access send(component). The body is read again when the
operation runs.

async saveAgain() {
  const payload = await createUser.send(this);
  console.log(payload?.result);
}

send() returns a Promise  | undefined> that resolves after the
operation completes. It

@put

@put replaces a resource with the body from a publisher. It uses exactly the
same model as @post:
Endpoint , DataProviderKey , ApiResult , options, and the
send(component) handle.

Minimal usage

const bodyKey = new DataProviderKey ("users.form");
const updateUser = put(new Endpoint ("users/42"), bodyKey);

@updateUser
@state()
payload?: ApiResult ;

The same decorator adapts to a method:

@put(new Endpoint ("users/42"), bodyKey)
handleUpdate(payload?: ApiResult ) {
  if (payload?.response?.ok) console.log(payload.result);
}

To run the operation again from the component:

async update() {
  await updateUser.send(this);
}

send(component) returns a Promise resolved after the PUT completes. See
@post for the method-decorator form and the
when: "before" option.

The PUT is also sent automatically when the body mutates, unless
autoPostOnBodyMutation: false is set. See
@post for the option details:

- autoPostOnBodyMutation
- skipIfBodyMissing
- refetchEveryMs
- skipEmptyPlaceholder
- triggerKey

Pass explicit API configuration as the third argument:

@put(endpoint, bodyKey, apiConfigurationKey)

Import

import { put, type ApiResult } from "@supersoniks/concorde/decorators";
impo

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