Alexandria
API & Development

Endpoints

Complete HTTP endpoint catalog of alexandria-server (/v1 and /pub) and of the alexandria-client admin API under specification v0.3.0.

Endpoints

In the tables below, Who is one of: public, admin, steward (of the namespace in the path) or steward or admin. See authentication for the rules.


1. alexandria-server — /v1

Responses are compact JSON-LD (application/ld+json). Lists are @graph documents. Errors are application/problem+json with a catalog code.

Namespaces and stewards

MethodPathWhoResult
POST/v1/namespacesadmin201 with Location. Body: slug, optional title, description.
GET/v1/namespacespublicAll namespaces.
GET/v1/namespaces/{ns}publicOne namespace.
GET/v1/namespaces/{ns}/stewardssteward or adminStewards of the namespace.
POST/v1/namespaces/{ns}/stewardsadmin201. Body: iss, sub, optional label.
DELETE/v1/namespaces/{ns}/stewards/{id}admin204.

Vocabularies

MethodPathWhoResult
POST/v1/namespaces/{ns}/vocabulariessteward201. Body: name, kind (hosted or proxy), media_type, upstream for proxies, optional title, description.
GET/v1/namespaces/{ns}/vocabulariespublicVocabularies with their revisions.
GET/v1/namespaces/{ns}/vocabularies/{name}publicOne vocabulary.
PUT/v1/namespaces/{ns}/vocabularies/{name}/contentsteward201 for a new revision, 200 when the bytes are unchanged. ETag is the digest. Optional If-Match.
POST/v1/namespaces/{ns}/vocabularies/{name}:refreshstewardRe-fetch a proxy upstream: 201 for a new revision, 200 when unchanged.

Drafts and candidates

MethodPathWhoResult
POST/v1/namespaces/{ns}/draftssteward201 with Location and ETag.
GET/v1/namespaces/{ns}/drafts/{id}stewardThe draft and its ETag.
PUT/v1/namespaces/{ns}/drafts/{id}stewardReplace. Requires If-Match (428, 412).
POST/v1/namespaces/{ns}/drafts/{id}:validatestewardReport: valid, class, findings[]. No effect.
POST/v1/namespaces/{ns}/drafts/{id}:proposesteward201 with the frozen candidate.
GET/v1/namespaces/{ns}/candidates/{id}stewardState, version, class, diff, planned record and lifecycle.
POST/v1/namespaces/{ns}/candidates/{id}:approvesteward201 with the signed VersionRecord. Optional body grace_window.
POST/v1/namespaces/{ns}/candidates/{id}:rejectstewardThe rejected candidate. Optional body comment.

Versions

MethodPathWhoResult
GET/v1/namespaces/{ns}/versionspublicThe signed VersionListing. Cache-Control: no-cache. 404 until the first release.
GET/v1/namespaces/{ns}/versions/{version}publicThe signed VersionRecord.
POST/v1/namespaces/{ns}/versions/{version}:revokestewardThe re-signed record. Body: justification, optional revoked_from.

Events

MethodPathWhoResult
GET/v1/eventsadminHub-wide event log.
GET/v1/namespaces/{ns}/eventsstewardEvents of the namespace.

Both accept after (an event id or IRI) and limit (default 100, maximum 500).

There are no list endpoints for drafts or candidates. Their ids appear in the namespace events (draft.created, candidate.proposed), which is how the console builds its index.


2. alexandria-server — /pub

All routes are GET, public and unauthenticated.

PathResult
/pub/{ns}303 to the head of the namespace.
/pub/{ns}/{version}/{path}A file of a published package.
/pub/{ns}/vocab/{name}303 to the latest revision.
/pub/{ns}/vocab/{name}/r/{n}A vocabulary revision.
/pub/packages/{digest}/manifest.jsonA signed PackageManifest.
/pub/blobs/sha256/{hex}A blob by its SHA-256.
/pub/_vhub/v1/context.jsonldThe JSON-LD context of Appendix A.5.
/pub/_vhub/v1/vocab.ttlThe vocabulary of the context terms.

Redirects carry Cache-Control: no-cache. Every other route is immutable: Cache-Control: public, max-age=31536000, immutable and an ETag equal to the SHA-256 of the body.

When the binary is built with the gui tag, /ui/ serves the console.


3. alexandria-client — Admin Listener

Unauthenticated, bound to its own listener. JSON responses; errors are application/problem+json.

MethodPathResult
GET/statusState, versions and roles, last accepted listing, hub DID, rules revision, clock skew.
GET/versionsLifecycle records with state and whether the package is held.
GET/rulesRule set; ETag is the revision.
PUT/rulesReplace the rule set. Requires If-Match.
POST/rulesAdd a rule. Requires If-Match. 201.
GET/rules/{id}One rule.
PUT/rules/{id}Replace one rule. Requires If-Match.
DELETE/rules/{id}Delete one rule. Requires If-Match. 204.
POST/rules:explainDecision for a described request, without effects.
GET/agreements/{id}A captured agreement with usable.
GET/audit/reports/latestLatest passive audit report, or 404.
GET/healthz200 while the process is alive.
GET/readyz200 in Active, Transition or Degraded; 503 otherwise.
GET/metricsOpenMetrics exposition.

4. Problem Documents

{
  "@context": "https://127.0.0.1:8443/pub/_vhub/v1/context.jsonld",
  "type": "https://w3id.org/alexandria-vhub/problems#API_FORBIDDEN_ROLE",
  "title": "API_FORBIDDEN_ROLE",
  "status": 403,
  "detail": "the principal has no permission for this operation",
  "code": "API_FORBIDDEN_ROLE",
  "severity": "error"
}
StatusTypical codes
400Unreadable request body (no catalog code).
401API_UNAUTHENTICATED
403API_FORBIDDEN_ROLE
404API_NOT_FOUND
409API_INVALID_STATE, NS_EXISTS, STEWARD_EXISTS, VOCAB_EXISTS
412API_PRECONDITION_FAILED
413VOCAB_TOO_LARGE
422NS_*, VOCAB_*, DATES_*, LIFECYCLE_*, compiler findings, RULES_*
428API_PRECONDITION_REQUIRED
502VOCAB_UPSTREAM_FAILED
503RELEASE_ABORTED, SIGNER_KEY_NOT_PUBLISHED

A validation failure with several findings returns one problem whose findings[] holds one entry per finding.

The repository ships Postman collections for both binaries in postman/.

On this page