Documentation

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:

OperatorMeaningExample
$eq[value]equalfilter[lname]=$eq[Mouse]
$neq[value]not equalfilter[lname]=$neq[Mouse]
$gt[value]greater thanfilter[age]=$gt[21]
$gte[value]greater than or equalfilter[age]=$gte[21]
$lt[value]less thanfilter[age]=$lt[65]
$lte[value]less than or equalfilter[age]=$lte[65]
$nullSQL IS NULLfilter[deleted_at]=$null
$ntnullSQL IS NOT NULLfilter[deleted_at]=$ntnull
$is[value]SQL ISfilter[state]=$is[NULL]
$isnt[value]SQL IS NOTfilter[state]=$isnt[NULL]
$uuid[value]UUID equality with repository conversionfilter[id]=$uuid[018f9e70-0000-7000-8000-000000000001]
$bin[value]binary equality with repository conversionfilter[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.