4.6 Listings, pagination, and the ?confirm= delete guard

These behaviors are part of the store contract (3.3), so they're identical on file, data, and any other store. This section is the practical reference for the two operations clients get wrong most often: listing/paging containers and deleting non-empty ones.

Listings

A trailing-slash GET lists a container as application/vnd.rs2.dir+json:

{
  "path": "/people/",
  "entries": [
    { "name": "ada", "dir": false },
    { "name": "archive", "dir": true }
  ],
  "total": 42
}

• entries — children at this level; dir: true marks a sub-container you can list in turn.
• total — the full count, also returned as the X-Total-Count header.
• Listings work at every level, including the mount root.

To walk a whole tree, recurse into entries where dir is true (the generic client loop, 3.3).

Pagination

Large containers page with two query params:

GET /data/events/?$take=100&$skip=200

X-Total-Count always reflects the full size, so a client can compute how many pages remain regardless of the page it asked for. (The $-prefix marks these as control params, distinct from query parameters a query mount would consume — see Part 6.)

Deleting a child

DELETE <child> returns 204. Straightforward.

Deleting a container — the ?confirm= guard

Deleting a container is guarded so you can't wipe a populated tree by accident:

DELETE /data/events/
→ 409 Conflict          (non-empty container)

DELETE /data/events/?confirm=events
→ 204 No Content

• An empty, unguarded container deletes with 204.
• A non-empty container returns 409; you must retry with ?confirm=<container name> to actually delete it.
• The data service goes further: dataset deletes always require the confirm token, empty or not.

A robust client treats 409 on a container delete as "ask for confirmation, then retry with ?confirm=" — exactly the generic loop step from 3.3.

That completes storage. Part 5 adds the other half of almost every real backend: authentication and access control.

← Previous: 4.5 Schemas, validation, merge PATCH · Manual home · Next: 4.7 Choosing a storage backend →