aster.Web Data / Docs Aster UI ↗

Aster Web Data / Start here

Get started

Serve a SQLite file as an OData API and query it with curl, in a few minutes.

In this guide you serve a small shop database, customers and their orders, as an OData API, then filter it, read customers with their orders, and add a customer. You need a terminal and curl. The database is a SQLite file, so there is no database server to install.

Download the server

Download the archive for your platform from downloads.getaster.now/webdata and unpack it. It holds one program, aster-webdata-server. Put it on your PATH, or run it by its full path.

Create the service

Make a folder called shop with four files in it:

shop/
  aster-webdata-server.yaml
  seed.json
  datasources/
    Customer.ds.yaml
    Order.ds.yaml

The configuration names the service and the database. setup: recreate creates the tables and loads the seed each time the server starts, dropping any that exist, so use it only on a database you can throw away:

# shop/aster-webdata-server.yaml
services:
  shop:                      # served at /shop
    namespace: Shop
    seed: seed.json
    datasources: [datasources]

databases:
  shop:
    kind: sqlite
    url_env: SHOP_DB_PATH    # the variable that holds the file's path
    setup: recreate

Each DataSource describes one table. The customerId field of an order refers to a customer, and inverseName gives each customer an orders list:

# shop/datasources/Customer.ds.yaml
dataSource:
  ID: Customer
  serverType: sql
  tableName: customers
  fields:
    - {name: id, type: sequence, primaryKey: true}
    - {name: name, type: text, length: 100}
    - {name: region, type: text, length: 8}

# shop/datasources/Order.ds.yaml
dataSource:
  ID: Order
  serverType: sql
  tableName: orders
  fields:
    - {name: id, type: sequence, primaryKey: true}
    - {name: customerId, type: integer, foreignKey: Customer.id, inverseName: orders}
    - {name: total, type: integer}

The seed holds the rows to load, under each DataSource's ID:

{
  "Customer": [
    {"id": 1, "name": "Ada Example", "region": "EU"},
    {"id": 2, "name": "Grace Sample", "region": "US"}
  ],
  "Order": [
    {"id": 10, "customerId": 1, "total": 120},
    {"id": 11, "customerId": 1, "total": 45},
    {"id": 12, "customerId": 2, "total": 300}
  ]
}

Start the server

From the shop folder, set the file's path and start the server:

export SHOP_DB_PATH=shop.db
aster-webdata-server --config aster-webdata-server.yaml

In PowerShell, set the path with $env:SHOP_DB_PATH = "shop.db". When the server is ready it prints:

aster-webdata-server listening on http://127.0.0.1:8080 (service root http://127.0.0.1:8080/shop)

Leave it running, and send the requests below from a second terminal.

Send your first requests

The customers in the EU, sorted by name:

curl -s 'http://127.0.0.1:8080/shop/Customer?$filter=region%20eq%20%27EU%27&$orderby=name'

The answer is JSON, with the matching customers in its value array. Each customer with their orders, the largest first:

curl -s 'http://127.0.0.1:8080/shop/Customer?$expand=orders($orderby=total%20desc)'

Add a customer. The server assigns the id and answers 201 Created with the new record:

curl -s -X POST 'http://127.0.0.1:8080/shop/Customer' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Lin Sample", "region": "EU"}'

Send the first request again, and Lin Sample is in the list. You wrote no endpoint for any of these: every set the model describes takes the same query options, and any other filter, sort or page is a different URL.

To see what the API publishes, read the service document and the metadata:

curl -s http://127.0.0.1:8080/shop/
curl -s 'http://127.0.0.1:8080/shop/$metadata'

Stop the server with Ctrl-C. It finishes any request in flight, then exits.

Next steps