Routes

Routes

The adapter serves the same route pack as dynamodb-toolkit/handler and the koa / express / fetch siblings. Routes are rooted at options.mountPath — a leading path prefix that is stripped from the event's path 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 return an empty 404. 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 event path + query (preserving mountPath, stage-less path, and other query parameters), so clients can follow them without reconstructing the base URL. See Event shapes → URL reconstruction for how the path and query are recovered per event shape.

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 on the trigger.

/-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 https://api.example.com/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 → empty 404.
• Unknown route shape (e.g. three path segments under the mount) → empty 404.
• 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.

The dispatcher is wrapped in a top-level try / catch; exceptions never escape back to the Lambda runtime (which would otherwise emit a raw 502 or a generic AWS error JSON). Every response goes through finalize() → the trigger's expected envelope shape. See Error handling.

Response headers

JSON responses carry content-type: application/json; charset=utf-8. No-content responses (204 / configured miss / 405 body omitted cases) carry no headers. The adapter adds no CORS / cache / security headers — configure them on the trigger (API Gateway response mappings, ALB listener rules) or wrap the handler.

Header shape (headers vs multiValueHeaders) flips automatically to match the request. See Event shapes → Multi-value headers.