Conventions

The conventions below hold across the whole contract. Most of them exist because the alternative failed quietly somewhere that mattered.

IdentifiersPermalink to this section

Resource identifiers are UUIDv7. They are globally unique like any UUID, and they sort by creation time, which means an index on the primary key is also an index on insertion order — a property that matters when the table holds a year of transactions.

MoneyPermalink to this section

Where a set of amounts spans currencies, it is presented as a set rather than summed. A single figure combining naira and dollars would be a defect that looks like a total.

PaginationPermalink to this section

Collection endpoints take a limit and a cursor and return the cursor for the next page. Cursor paging rather than offset paging is what keeps a list stable while it is being written to — an offset walk over a table receiving new rows shows some records twice and skips others, which for an alert queue means work that is silently never seen.

Idempotent writesPermalink to this section

Write paths that a client may reasonably retry accept a caller-supplied reference, and a retry carrying a reference already seen is not a second write. This is what lets an integration that timed out mid-batch simply send the batch again rather than reconcile it first.

TimePermalink to this section

Timestamps are RFC 3339 in UTC. The audit chain's canonical serialisation fixes them at microsecond precision, because a digest computed over a timestamp whose formatting varies is not a digest.

How the contract changesPermalink to this section

• Paths are versioned (/v1/...). A breaking change takes a new path rather than altering the meaning of an existing one.
• Adding an optional field or a new endpoint is not breaking, and clients must tolerate unknown fields.
• Every operation's required permission is part of the contract, not an implementation detail — a permission change is a contract change.