API Conventions

In one sentence. API Conventions is the set of cross-cutting rules — bulk-write semantics, identity/versioning, soft-delete-by-default, namespace-scoped authorization, response caching windows, and pagination — that every WIP REST and MCP surface follows the same way, so a caller who has read this doc once does not need to re-derive it per store.

Why it exists. WIP exposes several independently-implemented stores (document-store, template-store, def-store, registry) plus an MCP layer over them. The conventions exist so callers of any of them get identical semantics for writes, versioning, deletion, and authorization without deriving them per-endpoint, and so idempotent bootstrap scripts can provision a namespace, its templates, and its vocabularies against a fresh — or partially-provisioned — instance and simply be re-run on failure, "without ugly GET → 404 → POST dances or silent schema drift" (wip://conventions, "Idempotent Bootstrap"). The on_conflict=validate design explicitly favors loud failures over silent ones: "silent guardrails are worse than loud ones" (wip://conventions, "Template create with conflict validation").

The model

WIP has one identity mechanism per entity type; none of them are interchangeable:

Bulk write responses carry one status per submitted item — a 200 OK on the envelope says nothing about any individual item:

PATCH (update_document) applies an RFC 7396 JSON Merge Patch and can fail with any of: not_found, forbidden, archived, identity_field_change, append_only, concurrency_conflict, validation_failed, reference_violation, internal_error.

Namespace authorization is a two-axis model: a permission tier (read / write / admin grant, or superadmin) and an isolation mode governing what the namespace's documents may reference:

How it works

⚠ GAP: this doc's source_scope is wip://conventions (policy text) plus exactly one implementing module, the auth middleware. The store-level code that actually loops over bulk items, resolves template/document versions, or paginates a list response is not in scope — those live per-store (document-store, template-store, def-store, registry), each with its own doc in this library. This section documents the one mechanism whose implementation is in scope: authentication.

AuthMiddleware.dispatch (libs/wip-auth/src/wip_auth/middleware.py:69-121) runs on every request:

1. Public-path short-circuit. If request.url.path exactly matches an entry in self.public_paths — the universal set {"/", "/health", "/ready", "/docs", "/redoc", "/openapi.json"} plus whatever service-specific paths were passed to the constructor — the middleware sets the current identity to None, calls the downstream handler, and resets. No provider runs, so a stale or wrong credential header on a public path cannot 401 it.
2. Provider iteration. For any other path, the middleware tries self.providers in the order given to the constructor. The first provider whose authenticate(request) returns a non-None identity wins; iteration stops there.
3. Provider exception short-circuit. If a provider raises HTTPException (e.g., invalid credentials), the middleware converts it directly into a JSONResponse with the same status_code, detail, and headers, and returns immediately — remaining providers in the list are never tried.
4. No-match is not a rejection. If no provider returns an identity, identity stays None and the request still proceeds to call_next. The middleware itself never rejects an unauthenticated request; that is left to route-level dependencies (e.g. require_identity), which is what lets public and protected routes share one app and one middleware stack.
5. Context propagation. Whatever identity resolved to (None or a UserIdentity) is stored via set_current_identity(identity), which returns a token; call_next runs with that context set; reset_current_identity(token) restores the prior value in a finally block. The module notes this token-based save/restore exists specifically so a nested in-process call (e.g., the Registry called via ASGITransport) doesn't wipe the outer request's identity.

create_auth_middleware(providers, public_paths) (middleware.py:124-154) is the factory a service actually wires up: it returns a middleware subclass with providers and public_paths pre-bound for app.add_middleware(...). The module's own usage example pairs an API-key provider with an OIDC provider: providers = [APIKeyProvider(keys), OIDCProvider(issuer_url="...")].

Rules & invariants

• Bulk-first, always 200. Every write endpoint accepts arrays and returns 200 OK with one status per item — a caller must branch on results[i].status / error_code, never infer success from the outer status code. This is a WIP PoNIF — see PoNIFs.
• Templates keep old versions live. Updating a template does not retire the version it replaces — both stay active and can validate documents simultaneously until the caller explicitly deactivates the old one. Creating a document without an explicit template_version resolves to "latest active," which is ambiguous whenever more than one version is active. Also a PoNIF — see PoNIFs.
• Identity fields are the only dedup key, and they're all-or-nothing. Too few identity fields under-distinguish records; too many make every near-duplicate a distinct document; timestamps must never be identity fields (guarantees uniqueness, defeats dedup entirely) and should be avoided even outside identity fields (they force unnecessary version churn on otherwise-unchanged documents). A template with zero identity fields has no update path at all: every create_document call appends a new document, and PATCH always fails with append_only.
• PATCH cannot change identity. update_document deep-merges objects, replaces arrays wholesale, and treats null as field deletion — but any attempt to change an identity field is rejected (identity_field_change); to change identity you POST a new document instead. A patched version preserves the template_version and identity_hash recorded on the document it patched, so it validates against that version, not the template's current latest.
• on_conflict=validate has an asymmetric compatibility rule. For templates: identical schema is unchanged; adding an optional field is updated (new version, is_new_version=true); anything else (added required field, removed field, changed type, made-required, or an identity change) is error with error_code=incompatible_schema and a details breakdown (added_required, removed, changed_type, made_required, modified_existing, identity_changed). For terminologies/terms there is no partial-compatibility tier: any config difference under on_conflict=validate is error (incompatible_config); only an exact match is unchanged.
• Reference comparison at conflict-check time resolves synonyms. terminology_ref, template_ref, target_templates, target_terminologies, array_terminology_ref, array_template_ref (and the template-level source_templates/target_templates on relationship templates) are compared through the Registry first, so a value-form reference and its UUID synonym are treated as identical — a value↔UUID difference alone never trips modified_existing.
• Namespace PUT is an idempotent upsert with deletion-mode guardrails. Creating on a missing prefix uses platform defaults (isolation_mode='open', deletion_mode='retain', description='', empty allowed_external_refs); the default wip namespace can never be flipped to deletion_mode='full'; flipping an existing namespace from retain to full requires confirm_enable_deletion=true in the same request; a brand-new namespace may be created directly at deletion_mode='full' with no confirmation step.
• Soft delete is the default, with two independent hard-delete exceptions. Under deletion_mode='retain', deletes only flip status to inactive — nothing is physically removed. hard_delete=true requires deletion_mode='full'. Binary files (storage reclaim) and terms in mutable terminologies bypass this and can be hard-deleted regardless of the namespace's deletion_mode. An inactive term or document is still resolvable by anything that already references it, but is rejected as a new value — only active terms validate on write.
• No grant on a namespace looks identical to a missing namespace. A caller without a read/write/admin grant gets 404, not 403 — existence is not leaked. Superadmins (the wip-admins group) bypass grant checks entirely. Also a PoNIF — see PoNIFs.
• Relationship documents are the one exception to allowed_external_refs. For a relationship-usage (edge) document, source_ref/target_ref must resolve inside the edge's own namespace regardless of isolation_mode or allowed_external_refs — a cross-namespace edge is rejected (error_code=cross_namespace_relationship). The trade-off of using a plain document-reference field instead (to link across namespaces) is losing the /relationships and /traverse endpoints and the edge reporting columns same-namespace edges get. Reference validation itself runs at document-creation time, not template-creation time.
• API keys without an explicit namespace list have no access. A non-privileged key lacking a namespaces list (and not in wip-admins/wip-services) sees every namespace as 404. A single-namespace key gets its namespace derived automatically when the caller omits it; a multi-namespace key must pass namespace explicitly on every call, or raw values pass through with no synonym resolution at all.
• Two independent 5-second caches. Template "latest"-version resolution and namespace isolation-config reads (isolation_mode, allowed_external_refs) each carry a 5-second TTL; lookups by explicit template version are cached permanently since versions are immutable. A namespace allow-list change, or a template update, can take up to 5 seconds to become visible to a retried call.
• Pagination is fixed-shape. Default page_size is 50, max is 100; every list response includes a computed pages = ceil(total / page_size).

Gotchas

• A 200 OK from any bulk write can still contain per-item failures — check results[i].status before assuming anything succeeded.
• Updating a template doesn't deactivate what it replaces; two versions of the same template can be live and accepting documents at once unless you deactivate the old one yourself.
• A template with no identity_fields has no correction path — PATCH always fails append_only; the only way to "fix" a bad submission is a brand-new document.
• Multi-namespace API keys that omit namespace don't error — they silently skip synonym resolution and pass raw values through.
• After widening a namespace's allowed_external_refs, a write that was previously rejected can keep failing for up to 5 seconds — the namespace-config cache, not a propagation bug.
• isolation_mode='open' with a matching allowed_external_refs entry still won't let a relationship document's source_ref/target_ref cross namespaces — that allow-list governs plain reference fields only, not edges.
• The auth middleware's public_paths match is exact-string, not prefix: an API-prefixed health route like /api/registry/health is not covered by the universal /health entry — it has to be added explicitly, or the route requires a valid credential like any other.
• Provider order in AuthMiddleware is significant and not "try all and merge": the first provider to return an identity wins, and the first provider to raise HTTPException ends the whole chain — a later provider never gets a chance once an earlier one throws.

See also

• Data Model Reference
• Identity & the Registry
• Namespaces & Tenancy