Aster Web Data / Start here

Why Aster Web Data

What a screen costs as it changes when its endpoints are written by hand, and what changes with Aster Web Data.

An endpoint for one screen is quick to write by hand: a query, a few parameters and a JSON response. The cost comes with the next request from the people who use the screen. Each change has to be carried through the query code, the input checks, the API description and the client, and every new screen adds endpoints that need the same care. Aster Web Data serves every query option on every set it publishes from one model, so most of those changes are a different request, and the rest are an edit to the model.

An invoice screen as it grows

The finance team gets a list of unpaid invoices, newest first, a page at a time. Over the next few months they ask for five changes:

They ask for	With an endpoint written by hand	With Aster Web Data
A sort by customer name	A join to the customers table, a new sort parameter and its validation	The client sends `$orderby=customer/name`
"50 of 1,240" above the list	A second query that repeats the filter	The client adds `$count=true`, and Aster sends a count with the same filter
EU customers only	A filter on the joined table and another parameter	The client sends `$filter=customer/region eq 'EU'`
Each customer's region on the list	A migration, then the query, the response type, the API description and the client's types	The migration, then one line in the customer's DataSource
A paid invoice keeps its amount	A check in each endpoint that writes invoices	One rule in the rules file

The first three need no change on the server. The rule is one entry in the rules file:

rules:
  - id: PaidInvoiceLocked
    entity: Invoice
    host: {Property: amount}
    kind: ReadOnlyWhen
    condition: "paid eq true"
    message: A paid invoice keeps its amount

From then on, an update that changes the amount of a paid invoice is refused, and the error names the property:

HTTP 400
content-language: en
content-type: application/json;odata.metadata=minimal
odata-version: 4.01

{
  "error": {
    "code": "ValidationFailed",
    "message": "A paid invoice keeps its amount",
    "details": [
      {
        "code": "ReadOnly",
        "message": "A paid invoice keeps its amount",
        "target": "amount"
      }
    ]
  }
}

Change the model shows what each kind of model edit changes, and Rules covers the rules file. The screen itself can be built before the service exists: Aster UI's mock runs the same query engine in the browser, as described in In the browser.

What adopting involves

A model. One DataSource file per set: its fields and types, its keys and its relations to other sets. A database schema records how the data is stored; what it means is for you to write down and review. Connect your own database generates a first draft from an existing schema, and Model your data covers the format.
Database access. A connection URL in an environment variable or a file, and a database user with the privileges your sets need. What runs on your database lists them.
A deployment. One server process and a configuration file, behind the proxy or load balancer you already run. Health checks and metrics can be served on a separate port. Configure and deploy covers secrets, TLS, reloads and shutdown.

Who does what

Area	Aster Web Data	You
Queries	Parses OData 4.01 requests, plans them and runs each part in the database, or in its own engine within limits	The clients that send them, or Aster UI
SQL	Writes each statement in the database's own dialect, with values bound as parameters	The indexes on the columns your screens filter and sort by
Database behaviour	Translates each operator to the database operator with the same meaning	The database's collation, comparison and rounding, which decide the answer where the database runs the operation
Metadata	Publishes `$metadata`, the service document and OpenAPI from the model	The model: which tables, fields and relations to publish
Writes	Runs creates, updates, deletes, deep inserts and `$batch` in transactions, with ETags for concurrent edits	Rules the model cannot express, as rules or as Python or TypeScript scripts
Access	Verifies JWT bearer tokens, applies per-set access and row ownership, and refuses what a rule forbids	The identity provider and the roles or claims it issues
Schema	Checks the model against the database at start-up and with `check`	Schema changes and migrations
Operations	Health checks, reconnection after an outage, reload on `SIGHUP`, OpenTelemetry traces, metrics and logs	Hosting, certificates, secrets, the proxy and alert rules

Comparison and arithmetic rules gives the rules for each, and Is it a fit? lists the supported databases and features as a checklist.

When you don't need it

An API of a few stable endpoints over one table is simpler to write by hand, and Aster Web Data would add a model format, the OData query options and a rules file to learn. It is also the wrong tool when your clients need a query language other than OData 4.01, or when the main work is a workflow rather than reading and writing data. It pays off when several screens read and write the same data and their requirements keep changing.

Next step

Get started serves a SQLite database on your machine in about five minutes, and takes you through your first requests.