Routes

Routes

The adapter serves the same route pack as dynamodb-toolkit/handler. Routes are rooted at options.mountPath — a leading path prefix that is stripped from the incoming URL.pathname before route matching.

All requests and responses use JSON. The envelope shape, status codes, and - method-prefix are configurable via options.policy.

Summary

Method	Path	Adapter call	Response
GET	/	getList(opts, example, index)	200 — list envelope
POST	/	post(body)	204 — no body
DELETE	/	deleteListByParams(params)	200 {processed: N}
GET	/-by-names	getByKeys(keys, fields, opts)	200 — array of items
DELETE	/-by-names	deleteByKeys(keys)	200 {processed: N}
PUT	/-load	putItems(items)	200 {processed: N}
PUT	/-clone	cloneListByParams(params, mapFn)	200 {processed: N}
PUT	/-move	moveListByParams(params, mapFn)	200 {processed: N}
PUT	/-clone-by-names	cloneByKeys(keys, mapFn)	200 {processed: N}
PUT	/-move-by-names	moveByKeys(keys, mapFn)	200 {processed: N}
GET	/:key	getByKey(key, fields, opts)	200 — item, or 404 on miss
PUT	/:key	put({...body, ...key}, {force})	204 — no body
PATCH	/:key	patch(key, patch, patchOptions)	204 — no body
DELETE	/:key	delete(key)	204 — no body
PUT	/:key/-clone	clone(key, mapFn, {force})	204 / 404
PUT	/:key/-move	move(key, mapFn, {force})	204 / 404

Unrecognized route shapes (e.g. /a/b/c) and paths outside mountPath go through the miss path — see Composition for how onMiss picks between a terminal 404 Response and a null return for router composition. Known shapes with an unsupported method return 405 Method Not Allowed.

Collection root

GET /

Paginated list with an envelope and HATEOAS-style prev / next links when more data exists. The envelope keys are data / offset / limit / total / links by default — rename via policy.envelope.

Query parameters:

Param	Purpose
offset	Skip N items. Default 0, minimum 0. Hard-capped by policy.maxOffset (default 100000).
limit	Return up to N items. Default 10, clamped to maxLimit (default 100).
fields	Projection. Comma-separated dotted paths; see parent wiki for grammar.
filter	Filter expression in the toolkit's filter DSL.
sort	sort=field for asc, sort=-field for desc. Requires a sortableIndices entry for the field.
consistent	Pass true / 1 to enable strong consistency on the underlying read.

Example response:

{
  "data": [
    {"name": "earth", "mass": 5.97},
    {"name": "mars",  "mass": 0.642}
  ],
  "offset": 0,
  "limit": 10,
  "total": 2
}

Pagination links appear in a links object when more data exists. The adapter builds them from the incoming request URL (preserving mountPath, other query parameters, and protocol), so clients can follow them without reconstructing the base URL.

POST /

Create a single item. The request body is the item object; the Adapter's post() path runs hooks (prepare, validateItem) and enforces the partition-key-exists-not constraint. On collision the adapter throws ConditionalCheckFailedException → 409 Consistency by default (see Error handling).

DELETE /

Delete every item that matches the same filter query as GET /. Returns {processed: N} — the number of items actually deleted. Dangerous; often worth gating behind an admin auth policy.

/-by-names — bulk key operations

GET /-by-names?names=a,b,c

Fetch by key. Order of results mirrors the names list. Missing items are dropped from the response.

DELETE /-by-names?names=a,b,c

Delete by key. Also accepts an array body when the query is absent:

curl -X DELETE http://localhost:3000/planets/-by-names \
     -H 'content-type: application/json' \
     -d '["pluto","eris"]'

PUT /-load

Bulk create/replace; body is an array of items. Returns {processed: N}. Use for seed data or reloads.

PUT /-clone-by-names / PUT /-move-by-names

Clone or move named items. Body may be an array (the names list) or an object (an overlay merged into each cloned item). Both at once requires sending ?names=… in the query and an overlay object in the body.

/-clone / /-move — filter-based bulk ops

PUT /-clone?filter=…&fields=…

Clone every item matching the filter. Body is the overlay object merged into each cloned item.

PUT /-move?filter=…

Move every item matching the filter — semantically put(overlay ∪ item); delete(original) per item, chunked into transactions.

Item routes

GET /:key

Fetch one item. Returns 404 (by default) when the item doesn't exist — configurable via policy.statusCodes.miss.

PUT /:key

Create or replace. The URL :key segment is merged into the body so callers don't have to repeat themselves. ?force=true skips the existence check (blind overwrite).

PATCH /:key

Partial update. Body is a patch object; meta keys (prefix _ by default) carry options:

{
  "climate": "temperate",
  "_delete": ["retired"],
  "_arrayOps": [{"op": "add", "path": "visitors", "value": ["probe-42"]}],
  "_separator": "."
}

Everything without the _ prefix is treated as a field to set. See parsePatch for the full grammar.

DELETE /:key

Delete one item. Returns 204 regardless of whether the item existed — use GET first if you need miss detection.

PUT /:key/-clone / PUT /:key/-move

Single-item clone / move. Body is the overlay. Returns 204 on success, 404 (or configured miss status) when the source item didn't exist.

Dispatch behavior

• Path outside mountPath → miss path (see Composition). Default: empty 404 Response.
• Unknown route shape (e.g. three path segments under the mount) → miss path, same as above.
• Known shape, wrong method (e.g. POST /:key) → 405 Method Not Allowed with a JSON error body.
• Adapter throws → status + JSON body from policy.errorBody.

Response headers

JSON responses carry content-type: application/json; charset=utf-8. No-content responses (204 / configured miss / 405-less-body cases) carry no headers. The adapter adds no CORS / cache / security headers — wrap the handler for those.