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 shape | Allowed methods |
|---|---|
| Collection | GET, POST, DELETE, OPTIONS, HEAD |
| Entity | GET, 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:
| Method | Required header |
|---|---|
GET | Accept: application/vnd.api+json |
POST | Content-Type: application/vnd.api+json |
PUT | Content-Type: application/vnd.api+json |
PATCH | Content-Type: application/vnd.api+json |
DELETE | none required by preflight |
OPTIONS | none required by preflight |
HEAD | none 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+jsonRequest 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:
| Configuration | Header checked |
|---|---|
interface.language.content_language | Content-Language |
interface.language.accept_charset | Accept-Charset |
interface.language.content_charset | content-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.