EZ Move

API contract

This screen is the public explanation of the EZ Move API. Every server function is guarded twice: a wrong role is refused, and bad input is refused. The refusal body names the rule that refused, and when a field is wrong it names that field. Database error messages are never returned. Fake data only.

How a request is decided

  1. The session is checked. No session, a forged session, or an expired session is 401 sign_in_required.
  2. The role matrix is the first check. If this role may not perform that operation on that entity, the API returns 403 with rule: "role_matrix", plus the entity and the operation.
  3. Bad input is refused before the database writes. A missing required field returns 400 with rule: "required" and field. An unknown column returns rule: "writable_columns" and field. A value outside the written check (enum, range, positive integer, max length) returns that rule and the field. A non-integer id returns rule: "bad_id".
  4. Row policy is the second check. If the row is not this session’s to see or change, the API returns 403 with rule: "row_policy" (a row in another tenant looks like a row that does not exist on GET).
  5. A remaining database constraint is mapped to 422 with rule: "constraint". The database message is not returned.

Refusal shape

{
  "error": "missing",
  "rule": "required",
  "field": "name",
  "entity": "clients"
}

The published contract at /api/openapi.json (and /api/v1/openapi.json) documents the Refusal schema, including every rule name: role_matrix, writable_columns, row_policy, constraint, required, enum, range, positive_int, maxlen, bad_id.

Covered server functions

Contract tests walk the full set derived from the role matrix: every entity × role × operation (list, get, create, update, delete), every stats path, and the audit and metrics paths, plus a missing-field, unknown-column, bad-value, and bad-id probe on every write path that exists. They run on every change (npm test and the prebuild hook).

Live contract check

Enter as a demo persona on the plan-a-move screen, then return here. This page will read /api/openapi.json with that session and confirm the Refusal schema is published. It does not send real personal data; personas are fake.

Checking for a demo session…