Resource Access
Cleave exposes repository tables or collections as transactional resources under the
configured REST prefix. The default prefix is /api/0.0/.
Requests must also pass preflight checks for method, path, media headers, body length, and authorization. See Request Requirements for the complete request contract.
Collection requests address a resource type:
GET /api/0.0/person
Entity requests address a single resource identity:
GET /api/0.0/person/018f9e70-0000-7000-8000-000000000001
PATCH /api/0.0/person/018f9e70-0000-7000-8000-000000000001
DELETE /api/0.0/person/018f9e70-0000-7000-8000-000000000001
The collection name in the URI must match data.type for write payloads.
Fields
Use fields to select returned repository fields.
GET /api/0.0/person?fields=id,fname,lname
Include id or * in the field selection. Field names may
contain letters, numbers, _, $, ,, and *.
GET /api/0.0/person?fields=*
Special fields beginning with __ are protected by default on reads unless
interface.fields.get_allow_special is enabled.
Filters
Filters use one query parameter per field:
GET /api/0.0/person?filter[lname]=Mouse
A plain value is equality:
GET /api/0.0/person?filter[active]=true
GET /api/0.0/person?filter[age]=21
GET /api/0.0/person?filter[lname]=O%27Grady
Supported filter operators are encoded in the value:
| Operator | Meaning | Example |
|---|---|---|
$eq[value] | equal | filter[lname]=$eq[Mouse] |
$neq[value] | not equal | filter[lname]=$neq[Mouse] |
$gt[value] | greater than | filter[age]=$gt[21] |
$gte[value] | greater than or equal | filter[age]=$gte[21] |
$lt[value] | less than | filter[age]=$lt[65] |
$lte[value] | less than or equal | filter[age]=$lte[65] |
$null | SQL IS NULL | filter[deleted_at]=$null |
$ntnull | SQL IS NOT NULL | filter[deleted_at]=$ntnull |
$is[value] | SQL IS | filter[state]=$is[NULL] |
$isnt[value] | SQL IS NOT | filter[state]=$isnt[NULL] |
$uuid[value] | UUID equality with repository conversion | filter[id]=$uuid[018f9e70-0000-7000-8000-000000000001] |
$bin[value] | binary equality with repository conversion | filter[address]=$bin[ABCD] |
When value binding is configured as parameterized and the adapter supports it, scalar
comparison filters are bound as repository parameters. Null checks remain structural SQL
because they do not carry a scalar value.
Pagination
Use page[$skip] and page[$limit] for collection pagination:
GET /api/0.0/person?page[$skip]=0&page[$limit]=25
page[$skip] must be zero or greater. page[$limit] must be greater than zero and no more
than interface.paging.limit_max. Defaults currently come from configuration:
[interface.paging]
limit_default = 2
limit_max = 100
Cleave asks the repository for one more row than requested so the response can report whether another page exists.
Collection responses include pagination metadata:
{
"meta": {
"size": 25,
"hasNext": true,
"hasPrev": false,
"ext": "none"
}
}
Pagination links are returned under links.first, links.next, links.prev, and links.self
as applicable.
Sorting
Use order to choose the display order. A field name sorts ascending; prefix it
with - to sort descending. Separate multiple fields with commas:
GET /api/0.0/person?order=lname,-fname
This sorts by last name ascending, then first name descending. Request field names, not a SQL ordering expression.
Relationships
Related records appear under a resource's relationships member. Use the
relationship's identity and any returned links to retrieve related data, rather
than inferring a URL from a display label.
For example, a resource can identify its related account:
{
"relationships": {
"account": {
"data": {
"type": "account",
"id": "018f9e70-0000-7000-8000-000000000001"
}
}
}
}
Access to a resource does not automatically grant access to all related records. Cleave applies the configured access policy to the operations you request.
Writes
POST creates a resource. If data.id is missing, Cleave generates an identity.
POST /api/0.0/person
Content-Type: application/vnd.api+json{
"data": {
"type": "person",
"attributes": {
"fname": "Minnie",
"lname": "Mouse",
"age": 21
}
}
}
PATCH updates a specific resource:
PATCH /api/0.0/person/018f9e70-0000-7000-8000-000000000001
Content-Type: application/vnd.api+json{
"data": {
"type": "person",
"attributes": {
"lname": "Updated"
}
}
}
PUT upserts a specific resource using the identity in the URI:
PUT /api/0.0/person/018f9e70-0000-7000-8000-000000000001
Content-Type: application/vnd.api+json{
"data": {
"type": "person",
"attributes": {
"fname": "Minnie",
"lname": "Mouse"
}
}
}
By default, writes reject protected timestamp fields such as __created and __updated.
Write acknowledgement
Write responses normally report the affected-row count in meta.mod. If the request asks
for acknowledgement, Cleave reads the written entity back after the write.
Preferred form:
{
"meta": {
"write": {
"ack": true
}
},
"data": {
"type": "person",
"attributes": {
"fname": "Minnie"
}
}
}
Accepted aliases:
{ "meta": { "write_ack": true } }{ "meta": { "w_conc": { "ack": true } } }
If more than one acknowledgement form is supplied, the values must agree.
JSON extension type
The request can set meta.ext to choose how extended JSON values are parsed for that write:
{
"meta": {
"ext": "none"
},
"data": {
"type": "person",
"attributes": {
"fname": "Minnie"
}
}
}
Accepted values are none, segregated, and collated.