HTTP API on back(d)

Documents

Mon, 01 Jan 0001 00:00:00 +0000

Every configured collection gets the same set of endpoints:

Method	Path	Behavior	Success
`POST`	`/v1/{realm}/{database}/{collection}`	Create a document	`201` + `Location` + `ETag`
`GET`	`/v1/{realm}/{database}/{collection}`	List documents	`200`
`GET`	`/v1/{realm}/{database}/{collection}/{id}`	Fetch one document	`200` + `ETag`
`PUT`	`/v1/{realm}/{database}/{collection}/{id}`	Replace the whole document	`200` + `ETag`
`PATCH`	`/v1/{realm}/{database}/{collection}/{id}`	Partial update (JSON Merge Patch)	`200` + `ETag`
`DELETE`	`/v1/{realm}/{database}/{collection}/{id}`	Delete the document	`204`
`POST`	`/v1/{realm}/{database}/_batch`	Create, replace, patch and delete atomically	`200`

An unknown realm, database, collection or id returns 404 not_found. PUT and PATCH never create documents: there are no upserts, so create with POST and let the server choose the id.
In a realm with auth: enabled, requests are decided by the collection’s access rules, or allowed outright with an API key in Authorization: Bearer ….
Request bodies must be a single JSON object. Anything else returns 400 invalid_json.

Document shape

Documents are returned as bare JSON objects:

Querying

Mon, 01 Jan 0001 00:00:00 +0000

The list endpoint, GET /v1/{realm}/{database}/{collection}, accepts these query parameters:

Parameter	Default	Meaning
`where`	—	JSON object with filter conditions
`order_by`	`_meta.created_at,id`	Comma-separated fields; prefix a field with `-` for descending
`limit`	`20`	Page size, `1`–`100`
`skip`	`0`	Number of documents to skip
`after`	none	The `next_cursor` of the previous page: continues the list after it (see Paging with a cursor). Can’t be combined with `skip`
`count`	`false`	`true` adds `total`, the number of documents matching `where`
`deleted`	none	In a collection with soft delete: `only` lists the deleted documents (the trash), `include` both. Needs the `restore` rule besides `read`

Each parameter may appear at most once. Any other parameter returns 400 invalid_query.

Aggregations

Mon, 01 Jan 0001 00:00:00 +0000

A dashboard, a counter or a report needs summaries: orders per status, revenue per month, how many people did something. Without help that is a function per summary, or every document fetched and added up in the browser. GET …/_aggregate does it in the database, over only the documents the caller may read, with a fixed pipeline: the client picks declared fields, buckets and metrics, never database syntax.

Declare what can be summarized

A collection is opt-in: aggregate: in collection.yaml lists the fields a request may group by and measure. A collection without it answers 400 aggregate_not_enabled.

Full-text search

Mon, 01 Jan 0001 00:00:00 +0000

$contains looks for a substring and reads every document. Full-text search looks for words, through an index: it finds running in “He was running late” and “runs”, ranks documents by how well they match, and stays fast on collections that $contains would crawl through. It is declared per collection, in indexes.json, and used with $search in where: the reference has the request; this page is how to use it well.

Declare the index

[
 { "text": {
 "fields": { "title": 10, "tags": 5, "body": 1 },
 "default_language": "english",
 "language_field": "lang"
 } }
]

Pick the fields people search. Titles, names, tags, summaries and bodies; not ids, codes or numbers (use where on those). Fields are strings or arrays of strings, up to 30.
Weights say what matters. A word in a weight-10 title counts ten times a word in a weight-1 body, so “handbook” in a title beats “handbook” mentioned in passing. Start with 10 / 5 / 1 for title / keywords / body and adjust by looking at results.
One index per collection, a limit of the database: every searchable field goes in the same entry.
Changing it rebuilds it. Different fields, weights or languages replace the index at the next provisioning, with a warning in the log; searches answer 503 index_building meanwhile (with Retry-After; the JavaScript client retries 503s when its retry option is on). On a large collection do it at a quiet time.

Languages and stemming

Stemming reduces words to a root, so corriendo finds correr and shoes finds shoe; stop words (the, de, und) are ignored. Both depend on the language, in two places:

Caching and conditional GET

Mon, 01 Jan 0001 00:00:00 +0000

An app that reads the same documents again and again can ask the server “has this changed?” instead of downloading it again. backd answers with 304 Not Modified and no body when nothing changed. This page explains what that guarantees, how to do it by hand, and how a collection can let a CDN serve its public reads.

How a revalidation works

A read of a document or a list returns an ETag.
The next read of the same URL sends it back in If-None-Match.
If what the caller would receive is the same, the answer is 304 with the same ETag, Cache-Control and Vary, and no body. Otherwise it is a normal 200 with the new ETag.

GET /v1/shop/main/orders/ord_1
→ 200 ETag: "3"

GET /v1/shop/main/orders/ord_1
If-None-Match: "3"
→ 304 ETag: "3"

What the server still does

A 304 saves the transfer, not the work. On every read backd still runs the query and evaluates the read rule for the caller, and only then compares tags. That is why it is safe:

Realtime

Mon, 01 Jan 0001 00:00:00 +0000

A collection that declares realtime: true can be followed live. A client opens one stream for the whole realm with POST /v1/{realm}/_realtime, names what it follows, and receives the changes the caller may read as server-sent events.

POST /v1/shop/_realtime
Authorization: Bearer <session or API key>
Content-Type: application/json

{
 "subscriptions": [
 { "id": "mine", "db": "main", "collection": "orders", "where": { "status": "open" } },
 { "id": "order", "db": "main", "collection": "orders", "doc": "o_17" }
 ]
}

Read it with fetch and a streaming body: EventSource can’t send an Authorization header, and sessions never go in URLs.

Your realm's OpenAPI

Mon, 01 Jan 0001 00:00:00 +0000

The contract describes backd’s generic API: documents are open objects there, because their fields come from your config. A realm’s generated document is the same API with your config filled in: every collection with its schema, the sign-in methods the realm enables, its functions with their input and output. Generators of typed clients (openapi-generator, for Kotlin, Swift and many more) read it. Dart and Flutter apps use package:backd instead — a hand-written client that doesn’t come from a generator.

References and expansion

Mon, 01 Jan 0001 00:00:00 +0000

Almost every app has relations: a post’s author, an invoice’s customer, an item’s tags. Without help, each relation is another request and a join on the client. Reference expansion returns the referenced documents next to the result, in the same request, with one batched query per path for the whole page, and with every expanded document passing its own collection’s rules.

Four principles hold everywhere:

Declared and explicit. Only references declared in collection.yaml can be expanded, and only when the request asks. Nothing is expanded by default, and the JavaScript client never adds it by itself.
Additive. The document is exactly what schema.json says; expansions go in _expanded.
Rules everywhere. A referenced document is returned only if the caller could read it directly. Unreadable and missing look the same.
Bounded, visible cost. Limits on depth, paths, arrays and totals, and headers that say what a request cost.

Declaring a reference

# collection.yaml of "posts"
references:
 category: # the field "category" holds the id of a categories document
 collection: categories
 tags:
 collection: tags
 many: true # the field is an array of ids
 max_expand: 20
 author: # the owner's profile
 field: _meta.owner
 collection: profiles
 key: _meta.owner  # profiles has a unique index on _meta.owner
 customer:
 collection: customers
 database: crm  # another database of the same realm

Key	Default	Meaning
`collection`	required	the collection the values point to
`field`	the reference’s name	where the value is in this collection: a declared string field (an array of strings with `many`), a dotted path of one, `_meta.owner` or `_meta.created_by`
`database`	this database	the database of the target; always in the same realm
`key`	`id`	the field of the target that equals the value
`many`	`false`	the source is an array of values
`max_expand`	the instance’s value	follow at most this many ids of the array; only with `many`, and only lower than `BACKD_EXPAND_MAX_ARRAY`

How a value finds its document. The value of field is compared with key in the target: first id (the default), otherwise the field named by key, which can be a declared field or _meta.owner / _meta.created_by. Each value must match at most one document, so a key other than id needs a unique index of its own in the target’s indexes.json (one field; soft-delete’s extra key doesn’t matter).

HTTP API on back(d)

Documents

Document shape#

Querying

Aggregations

Declare what can be summarized#

Full-text search

Declare the index#

Languages and stemming#

Caching and conditional GET

How a revalidation works#

What the server still does#

Realtime

Your realm's OpenAPI

References and expansion

Declaring a reference#

Document shape

Declare what can be summarized

Declare the index

Languages and stemming

How a revalidation works

What the server still does

Declaring a reference