Aster Web Data / Build an API

With Aster UI

How Aster Web Data feeds Aster UI forms and grids, and where to read the Aster UI side.

Aster UI builds the screens: grids, forms and the views that share a record between them. Aster Web Data serves the data those screens read and write. A screen connects to one URL, the service root, and reads the service's metadata, which tells each control what a property holds and how it may be edited. A grid or form therefore takes its editors and filter operators from the model, rather than from types kept by hand in the screen's code.

How to build the screens is in the Aster UI guide, Integrate SQL and APIs.

What Aster Web Data provides

Aster UI connects to the service root and reads the metadata first. A connection is one call in the Aster UI library:

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

const ctx = await DataContext.connect(fetchTransport("https://shop.example.com/odata/"));
const products = ctx.collection(
  { set: "Product", orderBy: [{ field: "name" }] },
  { pageSize: 40, keepPages: 4 }
);

The collection is an OData query. Filtering, sorting and paging run on the server, as described in Query your data. Saving an edit is a write request, as described in Write data.

The service gives Aster UI four things:

• Metadata. Entity sets, property types, keys, relations, and the annotations that carry labels, allowed values and validation constraints. The Aster UI library reads the metadata when it connects.
• Queries. The query options the server supports, so a grid's sort and filter reach the database.
• Writes. Creates, updates and deletes with ETags and validation. A create answers with the saved record; an update does too when the request asks for it with Prefer: return=representation.
• Rules. The server enforces access and validation on every request, whatever the screen checked, so a form cannot save a value the server refuses.

Forms and grids from metadata

Controls choose their editors and filter operators from the metadata, which carries each property's type and its constraints.

Validation has two parts. The metadata carries the constraints a form can check before a save. The server runs its own checks on the write, and a refused write answers 400 with the code ValidationFailed. That answer lists one detail for each failed check, and each detail's target names the property, so a form can show each message beside its field.

A set's titles come from its definition: its title, its plural title, and the field that names one of its records. The annotations the service publishes are listed in the AsterData vocabulary.

A screen that needs a value the model does not have can compute it on the server. A computed property or an included field from a related set appears as an ordinary property in the metadata, so a grid can sort and filter by it as it would any other.

Build before the server exists

Aster UI can run against the same query engine in the browser, compiled to WebAssembly. A screen can then be built and tried before the server is set up. Replacing the transport with the service's URL points the same screen at the server when it is ready. See In the browser.

Virtual data sources

A set does not have to be a database table. A virtual data source is code you write that reads from another system, such as a REST API, and the service publishes it beside the SQL sets, with its metadata and queries. Aster UI uses it the same way. See Virtual data sources for the script you write, and the Aster UI guide for the screen side.

Next

• Query your data shows the requests a grid sends.
• In the browser runs the same engine without a server.