Running a node

API

Every route the node serves, what it accepts, and what it answers. The eight /dedi/lookup|query|versions routes are the DeDi standard's read API (api/openapi.yaml); everything else is this node's extension, and conformance says which is which.

Responses use the standard's envelope: {"message", "data"} on success, with a proof beside data when one was asked for, and {"message", "error", "code"} on failure.

Read routes

HTML pages: / (overview), /browse, /network, /status, /check, /verify, /docs, /docs/{page}, and /admin when the write plane is open.

Strict query parameters

The lookup, query and versions routes refuse a query they would otherwise answer by quietly ignoring part of it. Each of these is a 400:

• a key the route does not read (?versionId=2, ?asOn=…);
• a key given twice (?version_id=&version_id=2);
• a query string that does not parse (a stray ;, a bad % escape);
• on ?domain= discovery, any key other than domain and internal.

Why: ?versionId=2 used to return the latest version, with a valid proof attached. Every check a careful client ran passed, because they were all about the record the node chose to return rather than the one asked for.

Parameter meanings

• version_id pins one version. It is the log sequence number, the strings /dedi/versions lists and lookup returns as data.version. One that names no version of this resource, including a non-numeric one, is a 404; the standard types it as an unconstrained string, so it is not a malformed request.
• as_on answers "as of this instant": an RFC 3339 timestamp, or a YYYY-MM-DD date read as the end of that day in UTC. from takes the start of the day, to the end. Anything else is a 400.
• proof=inclusion attaches proof: the leaf, its index, the audit path, and the signed checkpoint it verifies against. Any other value is a 400.
• include_revoked=true lets a record lookup return a revoked current version (state: revoked) instead of 404. On subscribers.beckn.one it also returns a current version whose status is not SUBSCRIBED, which the Beckn lookup otherwise skips.
• internal=1 makes _-prefixed bookkeeping namespaces (_witness, _domains, _crawl, …) visible; without it they 404, so a crawler reading the standard's endpoints does not index them as directory data.
• sort is one of date, status, name, id (id sorts by name). page and page_size are positive integers; page_size defaults to 25 and is capped at 100.

Now, or settled?

A lookup is a settled read when it pins a version_id, or asks for an as_on more than one minute in the past. Its answer cannot change, so it is served Cache-Control: immutable for a year, and a revoked record still answers (history stays readable).

Anything else is a now read: no as_on, an as_on of today (end of day), in the future, or under a minute ago. It is cached for the record's ttl only, because that is how a revocation reaches a consumer, and a revoked record answers 404 unless include_revoked=true. The one-minute margin covers a write whose timestamp was stamped just before it committed.

Every lookup carries an ETag; send it back as If-None-Match for a 304.

Versions, three numbers

A write's response carries all three, so the next request never has to reconstruct one.

Write routes

Registered only when DEDI_PUBLISHER_KEYS is set; otherwise they, and /admin, answer 404. Every one needs a publisher signature (DeDi-Key-Id, DeDi-Timestamp, DeDi-Signature, from dedid sign or the console) by a key scoped to {ns}, and the Basic-auth gate when DEDI_ADMIN_PASSWORD is set. Bodies are JSON.

"Required" means If-None-Match: * (must not exist yet) or If-Match: <version_tag> (replace exactly this version). Both headers are inside the signature, so a captured request cannot be replayed without its precondition, and a replay lands as a 412 once the version has moved on. Publishing a record identical to its current version, or revoking one that is already revoked, is a no-op 200 with "unchanged": true rather than a duplicate version.

POST /enrol is the one write that is not signed: a child presents its one-time token there (delegation). POST /dedi/enrol is a deprecated alias.

Errors

One mapper handles every write failure, so the same cause gets the same answer on every route.

On a replicated node only the leader writes. Every write that reaches a follower and passes the admin gate and signature check is answered 307 Temporary Redirect to the same path on the leader, method and body intact, so a client that follows redirects needs little cluster awareness. When there is no leader, or the leader's public URL is not configured in DEDI_CLUSTER_PEERS, the follower answers 503 with code NO_LEADER and Retry-After: 2. Reads are served by every replica.

← All documentation