Skip to main content

RestDataProvider

REST data provider that maps the kanban's card actions (add-card, update-card, move-card, delete-card, duplicate-card) and column/swimlane actions to HTTP calls under a configurable URL root. Parses Date values on load and serializes them as ISO strings on send.

Reference backend implementation - https://github.com/svar-widgets/kanban-backend-go

Usage​

import { RestDataProvider } from "@svar-ui/react-kanban";

const provider = new RestDataProvider(url: string, config?: object);
ParameterTypeDescription
urlstringAPI root URL. Endpoints are appended as relative paths.
configobjectOptional config forwarded to the underlying Rest base (e.g. headers).

Wire the provider into the kanban via api.setNext(provider) inside the init callback.

REST endpoints​

ActionMethodEndpointNotes
add-cardPOST/cardsCard fields plus before (backend id of the anchor card, or null). Local id ignored; backend assigns the id
update-cardPUT/cards/:idDebounced 500 ms
move-cardPUT/cards/:id/moveFull payload including before; may include swimlane (PRO), which the backend must persist
delete-cardDELETE/cards/:id
duplicate-cardPOST/cards/:id/duplicateLocal id ignored; backend assigns the id

Column and swimlane endpoints​

Column and swimlane actions use the same pattern, where :axis is columns or swimlanes:

ActionMethodEndpointNotes
add-column / add-swimlanePOST/:axisFull config plus before
update-column / update-swimlanePUT/:axis/:idPartial config; debounced 500 ms
move-column / move-swimlanePUT/:axis/:id/moveBody is { before }
delete-column / delete-swimlaneDELETE/:axis/:id

An omitted before anchor is sent as null (append). Ids in URLs are encoded.

Id reconciliation​

When the backend returns a new id for an added card, column, or swimlane, the provider queue maps it to the local id. Later queued requests use the backend id in URLs, before anchors, and card membership. The local id on the board stays the same.

The id kinds are exported as constants from @svar-ui/kanban-provider:

import { CARDS, COLUMNS, SWIMLANES } from "@svar-ui/kanban-provider";
// CARDS = 1, COLUMNS = 2, SWIMLANES = 3

KanbanEventBridge maps incoming backend card ids to local ids for CARDS; COLUMNS and SWIMLANES payloads pass through unchanged.

Methods​

getData(): Promise<KanbanCard[]>

Sends GET {url}/cards and runs parseCards() on the result to convert deadline strings to Date instances. Returns the parsed cards array.

parseCards(data: KanbanCard[]): KanbanCard[]

Converts deadline strings to Date objects in place. Call it directly when loading raw payloads without getData().

formatDate(date: Date): string

Serializes Date values in outgoing JSON. Returns date.toISOString() by default. Override in a subclass to emit a different format (e.g. YYYY-MM-DD).

getHandlers(): ActionMap

Returns the internal action-to-REST mapping. Override in a subclass to add extra action handlers or change routing.

setHeaders(headers: Record<string, string>): void

Inherited from Rest. Sets headers sent with every request, e.g. an auth token or the X-Client-Id used with KanbanEventBridge.

Example​

import { useState, useEffect } from "react";
import { Kanban, Editor, RestDataProvider } from "@svar-ui/react-kanban";

const url = "https://api.example.com";
const provider = new RestDataProvider(url);

function App() {
const [api, setApi] = useState(null);
const [cards, setCards] = useState([]);

useEffect(() => {
provider.getData().then(data => {
setCards(data);
});
}, []);

const init = (api) => {
api.setNext(provider);
};

return (
<>
<Kanban ref={setApi} init={init} cards={cards} columns={columns} />
{api && <Editor api={api} />}
</>
);
}
  • Working with server - loading, saving, and dynamic data
  • setNext - wires the provider into the event bus
  • init - callback where the provider is typically attached
  • KanbanEventBridge - replays changes from other clients through a server-sent events stream