Aster UI / Guides

Build a web application over SQL and backend APIs

Aster provides a path from existing systems to a working web interface. Aster WebData supplies the server integration mechanism: virtual data sources. You implement the code that reads or writes your backend, declare its fields, and register it with the server. WebData exposes that source through OData, including metadata and query handling. Aster UI connects to that service and uses the data in grids, forms, tiles and other views.

OData is the common contract WebData provides to the UI. Your original database, REST API, CLI or legacy service keeps its native interface.

What you implement and what Aster provides

The virtual-source interface is part of WebData. Backend-specific code plugs into that interface; metadata generation and OData request processing belong to the server.

Example: combine SQL customers with account status from an API

Suppose customer names and contact details live in SQL, while account status comes from your existing backend API. You want one customer workspace in a web application, with filtering, paging and an editor.

Define the SQL-backed customer source and a virtual source for the backend API. If the screen needs a combined row, register a virtual CustomerWorkspace source whose read handler fetches customer records through the engine, calls your API and matches the results by customer ID. Cross-source engine calls let the handler participate in the same server data layer as other sources.

The handler owns that matching logic. A source definition for its returned rows can look like this:

dataSource:
  ID: CustomerWorkspace
  serverType: virtual
  handler: customer_workspace
  fields:
    - { name: id, type: integer, primaryKey: true }
    - { name: name, type: text, length: 200 }
    - { name: accountStatus, type: text, length: 40 }

The registered customer_workspace handler implements WebData's VirtualSource contract. Its fetch method returns records matching that schema. A Rust handler can use its own HTTP client or CLI integration, and the supplied context provides engine calls such as fetch and get for other data sources.

Once the definition and handler are registered, WebData publishes the entity set and its metadata. The UI can request:

GET /odata/CustomerWorkspace?$filter=accountStatus%20eq%20%27Active%27&$orderby=name&$top=40

WebData handles the OData request. A minimal handler supplies the complete, bounded result for the engine to filter, sort and page. For a large source, declare and implement query pushdown so the handler can ask the underlying system for the relevant data efficiently.

Bind the resulting data to a grid

Given that service and an existing <aster-grid> element, the UI connection is the same as for a SQL-backed entity set:

import "@getaster/elements";
import { DataContext, fetchTransport } from "@getaster/data";

const ctx = await DataContext.connect(fetchTransport("/odata/"));
const customers = ctx.collection(
  { set: "CustomerWorkspace", orderBy: [{ field: "name" }] },
  { pageSize: 40, keepPages: 4 }
);

const grid = document.querySelector("aster-grid");
grid.ctx = ctx;
grid.collection = customers;
grid.view = {
  columns: [{ field: "name" }, { field: "accountStatus" }],
  sort: [], filters: {}, frozen: 0,
};

The context loads the published metadata. Controls use its field types and annotations for editors, filtering and validation feedback. Other views can share the collection and selection, or open an edit model over a selected row. See Get started for page setup and connect a grid and form for editing.

Write through the same integration

A virtual source can implement add, update and remove as well as fetch. Declare the writes it supports and implement their backend-specific behaviour. An edit saved through Aster UI then travels through OData to the source's write handler; the returned record updates the shared UI data model.

Write handlers and server operations can also call other data sources through the engine. For example, a workflow can update a SQL customer record and request an account change from your API. Source permissions, execution context and external failure handling still apply.

Cross-source workflows and distributed transactions are different requirements. Atomic write support depends on the participating backends' declared transaction capabilities; calling several systems does not make their external effects atomic. Automatic joins across arbitrary backends are also separate from a handler that combines records explicitly. Check the server release's supported operations and design partial-failure handling for the workflow.

Choose this path for an integration application

This combination is useful when you want to bring existing systems into an interactive application: backend code implements virtual sources, WebData gives them a common service contract, and the UI supplies connected data views.

Use Aster WebData for the companion server and its setup documentation. The npm UI packages contain the client data layer and controls; see installation and distribution for those packages, the shared data model for client ownership, and the fit assessment to compare this approach with your project's needs.