Your repository schema remains the source of truth.
Cleave brings a consistent transactional API directly to your repositories, without a separate schema-mapping or API-generation step. Your repository schema remains the source of truth, with no duplicate mapping to maintain as it changes.
Use the schema you already have
For supported repositories, you do not need to describe your tables, collections, and fields again in a separate Cleave schema. There is no domain model to translate into repository operations and no API-generation step to run before accessing your resources.
Cleave provides the common machinery for resource access, filtering, relationships, validation, and authorization directly over the repository. Applications can focus on their user experience and business logic.
Change the repository without maintaining a second schema
When your underlying schema changes, there is no corresponding Cleave mapping to update or synchronize. The repository changes once. There is no second schema to keep in step. Adding a field does not mean adding it again to a mapping file and regenerating a transactional API.
You still manage repository migrations, constraints, indexes, and application compatibility. Renaming or removing a field can affect clients that use it. Cleave removes the separate mapping maintenance from that work.
Use the same operations across screens
A contact list, product catalogue, and support queue all need filtering, sorting, pagination, and access to related records. Cleave provides those operations through a shared resource interface. Each screen chooses the resources and fields it needs; the application does not need a separate handler for every combination. Different screens can ask different questions through the same interface.
Business actions such as approving an expense or submitting a payment can remain explicit calls to your backend. That backend applies the business rules and uses Cleave for the repository operations involved.
Follow the query instead of rebuilding it
The response tells you whether there is another page. No extra request to find out. A list can enable Next when more results exist and stop offering it when the collection is exhausted.
Cleave's collection responses can supply self, first, prev, and next
links where applicable. A frontend can use them to navigate results rather than
reconstructing pagination URLs and remembering which filters belong on each one.
These link names follow the familiar
JSON:API pagination conventions.
For example, an address list is filtered to Massachusetts and displays two records at a time. Its next-page link keeps the filter and selected fields:
/api/0.0/address?page[$skip]=2&page[$limit]=2&filter[state]='MA'&fields[address]=id,street
Here, page[$skip]=2 moves past the first two records. The state filter and
id,street field selection stay in the link. The frontend follows it instead
of assembling another request. Next means more of the same query, with the
same filters. First and Previous work within the same selection.
On the second page, with another page available, the response's links object
looks like this (shown with relative URLs for readability):
{
"links": {
"self": "/api/0.0/address?page[$skip]=2&page[$limit]=2&filter[state]='MA'&fields[address]=id,street",
"first": "/api/0.0/address?page[$skip]=0&page[$limit]=2&filter[state]='MA'&fields[address]=id,street",
"prev": "/api/0.0/address?page[$skip]=0&page[$limit]=2&filter[state]='MA'&fields[address]=id,street",
"next": "/api/0.0/address?page[$skip]=4&page[$limit]=2&filter[state]='MA'&fields[address]=id,street"
}
}
A frontend or backend can take links.prev or links.next as returned and
request that URL directly. The link carries the page selection, filter, and
selected fields: there is no separate query state to store or reconstruct to
continue this list. The client simply sends its credentials with the request
as usual.
No URL concatenation, no splitting the query into parts, and no assumptions about how the server builds its links. Use the returned URL as it is.
On the first page there is no previous-page link; on the final page there is no next-page link.
This is a practical use of HATEOAS: the response supplies the navigation the
client needs. The link's relation, such as next, describes its purpose, so a
reusable list component can follow it without knowing how the server constructs
the URL.
For body-based QUERY requests, Cleave supplies request descriptors relative to
self, with overrides for the page selection. A client can continue the existing
query without rebuilding its body. It interprets the descriptor to make the next
request, rather than assuming every continuation is a GET URL.
The client still sends its credentials, and Cleave checks access on each request. Following Next retains the query; it does not bypass record permissions.
See Resource Access for pagination details.
One contract across application features
RIP, the Repository Interface Protocol, describes the application-facing contract. Its adapters interpret requests and format responses. RAP, the Repository Access Protocol, supplies the common transactional operations and their validation and authorization semantics; repository adapters handle native execution.
A frontend list can therefore use the same filtering and pagination conventions across resources, while Cleave applies the configured validation and permissions. The adapter determines how those requests and responses are represented on the wire. See Architecture for the layer boundaries.
Add record capabilities when you need them
Optional record fields support owner/group/other access control and track when records are created and updated. These fields enable specific capabilities; they are not a mandatory domain schema for every resource.
For access control, owner and group IDs identify who owns a record and which group it belongs to. Permissions determine the access allowed to the owner, members of that group, and other users. The fields needed depend on the access-control mode you enable; resources with access control disabled do not need ACL fields.
Creation and update timestamps provide record lifecycle metadata when your application needs it. Together, these conventions add transactional capabilities without requiring you to duplicate your business schema.
Repository connection settings, resource naming, and adapter-specific identity conventions still apply. See Repository Initialization for the current setup details.