Repository Initialization
Repository initialization should make the transactional contract explicit before production traffic reaches Cleave.
Cleave does not invent a domain schema. It expects the repository to contain tables or collections that match the public resource names exposed through the API.
Resource names
A request to:
GET /api/0.0/person
targets the person repository resource.
Write payloads must use the same type:
{
"data": {
"type": "person",
"attributes": {
"fname": "Minnie"
}
}
}
If data.type does not match the URI collection name, Cleave rejects the request.
Identity field
Cleave expects resources to have an id field.
Entity URLs use that identity:
GET /api/0.0/person/018f9e70-0000-7000-8000-000000000001
The repository adapter determines how that value maps to storage:
- MySQL repositories should store Cleave UUID identities in
BINARY(16)columns; - PostgreSQL repositories should store Cleave UUID identities in
uuidcolumns.
POST can generate an ID when data.id is omitted. PUT uses the identity from the URI for
upsert.
Protected metadata fields
The default write configuration forbids clients from setting:
__created;__updated.
These fields are intended to remain repository/system controlled.
On reads, fields beginning with __ are hidden unless interface.fields.get_allow_special is
enabled. When returned, nested metadata formatting places those fields under resource
meta.
Access policy
Choose whether resources are private to a user, shared with a group, or available under owner/group/other permissions. Prepare existing records with ownership and permissions that match that policy before exposing them to clients.
Use the setup supplied with your application or repository adapter for that preparation. Ownership and permissions are service-managed metadata, not ordinary form fields. Clients should send application attributes and their signed token.
See Access Control for a team policy and concrete read, update, and delete requests. Test the same record as its owner, a colleague, and an unrelated user before serving production traffic.
Indexes
Index fields that appear in common request paths:
id;- frequent
filter[...]fields; - fields used for repository ordering when sorting is enabled;
- ownership and group lookups used by the selected access policy;
- relationship keys used by joins or relationship projections.
Cleave can keep request shape bounded, but it cannot make an unindexed high-cardinality filter cheap.
Initialization checklist
Before serving traffic:
- create the resource tables or collections;
- add
idwith repository-appropriate UUID storage; - add protected metadata fields if the application needs created/updated timestamps;
- initialize record ownership and permissions for the selected access policy;
- add indexes for common filters and ACL checks;
- configure reader and writer endpoints;
- set
page_limit_maxfor the service's expected traffic pattern; - decide whether protected
__fields should be readable; - run GET, POST, PATCH, PUT, DELETE, and filtered collection requests against a test resource.