Documentation

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 uuid columns.

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 id with 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_max for 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.