APIs, integrations & migration

REST API for collections

Lets a client application read and write any collection through one generic set of URLs, without a hand-written endpoint for each resource.

BetaEngine edition 5f8ea3af

What it does

Every collection is served at /rest/v1/<name> with list, insert, update and delete, a filter grammar in the query string, column selection, sorting, offset paging and one level of relation embedding. It runs behind the same authentication, collection rules and row-level policies as the other record endpoints. List, update and delete read the whole collection before they filter, so the layer suits small and medium collections today.

How it works

A request names a collection in the path. The server resolves the caller from the project key or user token, finds the collection definition for that project and checks the collection rule for the operation: list, create, update or delete. A missing collection is a 404 and a denied rule is a 403. Records belong to one project. For project keys and project tokens the project comes from the credential, and a request header cannot widen it.

Filters are written as column=operator.value in the query string. The operators are eq, neq, gt, gte, lt, lte, like, ilike, in and is (null, notnull, true, false), and any of them can be negated with a not. prefix. The or and and parameters take a parenthesised list, for example or=(status.eq.open,priority.gt.2). The id, created_at and updated_at fields can be filtered like any attribute. Full-text matching through this layer is refused with a message that points to the search endpoints, and so is a stored-function call, which points to the KynQL query endpoint.

select chooses columns, with * for all of them. A name followed by parentheses, such as select=id,title,author(name), embeds a relation: the name is a relation field of the record, and the response carries the target record, or an array for a multi-valued relation, with the field visibility of the target collection applied for the caller role. Embeds go one level deep.

order takes a comma-separated list such as order=created_at.desc,title.asc; without it the most recently updated record comes first. limit defaults to 50 and is capped at 1,000, offset skips records, and a Range header (zero-based, inclusive) sets both. Prefer: count=exact puts the total in the Content-Range response header; without it the header ends in an asterisk.

POST inserts one object or an array. Prefer: resolution=merge-duplicates turns the insert into an upsert by id, and Prefer: return=representation echoes the stored rows. PATCH merges the body into every matching record and DELETE removes every matching record. A request can carry an x-idempotency-key header of up to 200 bytes. The server records the outcome for 24 hours, replays it for a retry of the same request, and refuses the same key reused for a different request. Writes publish realtime events and are handed to any configured outbound database sink.

Where you reach it

  • HTTPGET /rest/v1/:table (list, filter, select, order, limit, offset)
  • HTTPPOST /rest/v1/:table (insert one or many; upsert with Prefer: resolution=merge-duplicates)
  • HTTPPATCH /rest/v1/:table?<filter> (merge a body into every matching record)
  • HTTPDELETE /rest/v1/:table?<filter> (delete every matching record)
  • ConfigKYNETRA_CORS_ORIGINS (allowed browser origins; when unset, same-origin requests work and cross-origin requests are not allowed)

Example

Open orders over a threshold, with the customer embeddedbash
curl -s "$BASE/rest/v1/orders?select=id,total,customer(name)&status=eq.open&total=gte.100&order=created_at.desc&limit=20" \
  -H "Authorization: Bearer $KEY" \
  -H "Prefer: count=exact"

Limits

  • List, PATCH and DELETE read every record of the collection and then filter, sort and page in memory. The cost grows with the size of the collection and no scale has been measured. For large collections use the search, vector and KynQL endpoints.
  • Paging is by offset. There is no cursor, so a deep page re-reads the collection, and records added between two requests can shift the window.
  • A PATCH or DELETE with no filter applies to every record the caller may change. Always send a filter.
  • Embeds follow relation fields one level deep. Nested embeds and reverse relations are not supported.
  • Sorting orders numbers and text. Other value types compare as equal.
  • The OpenAPI document does not describe these routes.
  • Writes through this layer do not raise outbound webhook events.

Evidence

  • On this siteData access integrations that call the REST layer
  • On this siteAPI reference: authentication and route groups
  • TestsCovered in the engine repository by more than 40 unit tests of the query grammar (each filter operator, or and and groups, select with an embed, ordering, the limit cap, the Range header, the Prefer headers), 8 idempotency tests (claim, replay, key reuse, abandoned claim, per-project isolation) and mounted-router tests for reserved rows and tenant scoping

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.