Documentation

Request Requirements

Cleave checks every request before it reaches a resource handler. These checks keep request shape explicit and reject calls that do not match the configured resource boundary.

Resource shape

Requests must target either a collection or an entity under the configured REST prefix. The default prefix is /api/0.0/.

When a request fails these checks, Cleave returns a structured error response. See Error Responses for status codes and details values.

Collection requests target a resource type:

/api/0.0/person

Entity requests target a resource type and identity:

/api/0.0/person/018f9e70-0000-7000-8000-000000000001

Entity IDs may be supplied as 32 hexadecimal characters or as a hyphenated UUID. A trailing slash on an entity path is rejected as malformed.

Method rules

Cleave distinguishes collection methods from entity methods.

Resource shapeAllowed methods
CollectionGET, POST, DELETE, OPTIONS, HEAD
EntityGET, PUT, PATCH, DELETE, OPTIONS, HEAD

POST creates through a collection endpoint and cannot be used on an entity endpoint. PUT and PATCH operate on a specific entity and cannot be used on a collection endpoint.

Unknown methods are rejected. Methods that Cleave knows but does not allow for the resource shape are also rejected before the request reaches the method handler.

Media headers

Cleave currently checks media headers by method:

MethodRequired header
GETAccept: application/vnd.api+json
POSTContent-Type: application/vnd.api+json
PUTContent-Type: application/vnd.api+json
PATCHContent-Type: application/vnd.api+json
DELETEnone required by preflight
OPTIONSnone required by preflight
HEADnone required by preflight

For writes, send JSON:API media type on Content-Type:

POST /api/0.0/person
Content-Type: application/vnd.api+json
Content-Length: 96

For reads, send JSON:API media type on Accept:

GET /api/0.0/person
Accept: application/vnd.api+json

Request bodies

GET requests must not carry content. If a GET request includes Content-Length, Cleave rejects it as malformed.

POST, PUT, and PATCH requests must include Content-Length. The value must parse as a non-negative integer and must not exceed http.req_body_maxlength.

The default request body limit is:

[http]
req_body_maxlength = 10000

URI length is also bounded by configuration:

req_uri_maxlength = 500

Requests whose normalized collection cache key is longer than the configured URI limit are rejected before repository access.

Optional language and charset gates

The following header checks are disabled when the matching configuration value is empty:

ConfigurationHeader checked
interface.language.content_languageContent-Language
interface.language.accept_charsetAccept-Charset
interface.language.content_charsetcontent-charset

When configured, the header must be present and must exactly match the configured value.

Accept-Language is intentionally advisory until localized responses exist. Clients may send it, and deployments may record or inspect it, but it should not be treated as a required request gate for normal resource access.

Authorization

When auth.ignore_auth = true, Cleave skips bearer-token verification.

When authentication is enabled, requests must include:

Authorization: Bearer <jwt>

JWT claim requirements depend on the configured access-control mode. See JWT Authentication and Access Control.

Service availability and forbidden collections

interface.service_available can restrict access by client IP. When this list is empty, Cleave does not apply an IP allow-list. When it is populated, the client address must match one of the configured addresses.

Forwarded client IP headers are used only when interface.use_forwarded_headers = true and the TCP peer is listed in interface.trusted_proxy_ips.

interface.collections.forbidden rejects configured collection names before repository execution.