devrites-api-interface

devrites-api-interface — contract before implementation

When a slice crosses a boundary (FE/BE, service/service, module/module) or exposes a public interface, define the contract first so both sides can proceed and the interface stays stable.

Define the contract first

• Shape — request/response or function signature; field names, types, optionality, units. Follow the project's existing naming and conventions.
• Status & errors — success codes, error codes, error body shape, validation messages. Errors are part of the contract, not an afterthought.
• Semantics — idempotency, pagination, ordering, nullability, side effects.
• Versioning/compat — is this new or a change to an existing contract? A breaking change to an existing consumer is a user decision (and a drift event if unplanned).

Stability principles

• Design for the caller. The interface should make the common case easy and the wrong call hard.
• Be conservative in what you expose; you can add later, but removing/changing breaks consumers.
• Match existing endpoints/modules in style — don't introduce a competing convention.
• Validate at the boundary (untrusted → trusted); don't trust caller-supplied trust signals (IDs, roles). (See rite-review/reference/security-review.md three-tier.)

Enables the split

A clear contract lets /rite-plan split proceed: the backend slice can land against the contract with a stub consumer; the frontend slice can build against a mock or the real contract. Neither side blocks on the other.

Doubt the contract

Before standing the interface, run devrites-doubt — boundary decisions are exactly the non-trivial kind worth an adversarial check. Record the contract + rationale in decisions.md.

Gotchas

• Be conservative — you can add to a contract later, but removing or changing a field breaks every consumer.
• Validate at the boundary; never trust caller-supplied IDs, roles, or prices.
• A breaking change to an existing consumer is a user decision (and a drift.md event if unplanned), not a silent edit.
• Match the project's existing endpoint/module conventions; a competing convention is a tax, not a design.