F12.1 — :batchGet and :batchUpdate
| State | Closed |
| Parent | E12 |
| Iteration | Release 3 |
| Start Date | 2026-10-04 |
| Closed Date | 2026-10-04 |
| Predecessors | F12.15 |
| Source | Owner request, 2026-10-04 |
Stories: 5 Closed
| Story | State | Depends on |
|---|---|---|
S12.1.1 — Shared batch rules in rn-forge-web |
Closed (2026-10-04) | — |
| S12.1.2 — Conformance cases | Closed (2026-10-04) | — |
| S12.1.3 — Django binding | Closed (2026-10-04) | — |
| S12.1.4 — FastAPI binding | Closed (2026-10-04) | — |
| S12.1.5 — Documentation and release notes | Closed (2026-10-04) | — |
The API conventions' §19 spells :batchGet and :batchUpdate (AIP-231,
AIP-234) and says they are built when a consumer needs them. Neither stack has
them. This feature adds the handlers on both stacks, with the wire rules in
rn-forge-web and conformance cases that pin them. It follows
F12.15's pattern: Django mixins,
FastAPI route factories over application stores, one wording for both.
Context
Outcome: the owner scheduled this feature for release 3 on 2026-10-04, ahead
of its original trigger, to complete the batch set that :batchCreate and
:batchDelete started, reusing F12.15's shared list rules.
Design
Outcome: both methods shipped all or nothing on both stacks (2026-10-04). The API conventions §17 own the wire rules; the Django transfer guide and the FastAPI transfer guide show the bindings.
Shared pieces in rn-forge-web
Outcome: the transfer reference documents the shared symbols and their contracts.
New conformance cases
Outcome: the cases are in CASES, in the transfer area, documented in the
conformance reference; the API
conventions name each case id beside its rule.
Out of scope
- Partial success. AIP-234 allows an
allow_missingupsert and partial results. Both batch methods stay all or nothing, as:batchCreateand:batchDeleteare. readMaskon:batchGet. F12.9 adds it.
S12.1.1 — Shared batch rules in rn-forge-web
State: Closed (2026-10-04)
Acceptance:
rn_forge.webexportsInvalidBatchGet,batch_get_ids,NON_EMPTY_IDS_DETAIL,DUPLICATE_ID_DETAIL,BatchUpdateItem,parse_batch_updateandcheck_item_precondition, with the contracts in Shared pieces.PreconditionRequired,MalformedPreconditionandVersionConflictaccept an optionalerrorsargument. Without it, their rendered bodies are unchanged; every existing concurrency case still passes.tests/test_transfer.pyandtests/test_concurrency.pycover each new function: every step of both tables, ids given as strings or integers, emptyidsvalues dropped, and*as an item'sifMatch.
S12.1.2 — Conformance cases
State: Closed (2026-10-04)
Acceptance: RequestSpec.query accepts str | tuple[str, ...] values, and
both drivers send a tuple as a repeated parameter. CASES gains the cases in
New conformance cases, in the transfer area. Both
drivers run every case with no skips.
S12.1.3 — Django binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.drf.transferexportsBatchGetMixinandBatchUpdateMixin, served byCustomMethodRouterat{collection}:batchGetand{collection}:batchUpdate.- The Django conformance fixture serves
/conformance/booksand/conformance/capped-booksthrough them, and the new cases pass. tests/drf/covers what the cases do not reach:validate_batch_update_itemdenying an item (403, nothing written),batch_update_requires_if_match(428 with the pointer), audit fields set on every updated row, an unversioned model ignoringifMatch, and afilter_querysetscope hiding an id (404), and an id the key cannot hold (404, also for:batchDelete).- The drf-spectacular schema names the operations
booksBatchGetandbooksBatchUpdate.
S12.1.4 — FastAPI binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.fastapi.transferexportsBatchGetStore,BatchUpdateStore,batch_get_routerandbatch_update_router.- The FastAPI conformance fixture serves
/conformance/booksand/conformance/capped-booksthrough them over an in-memory store, with no hand-written handler for those paths, and the new cases pass. tests/test_transfer.pycovers a store raisingItemsDenied(403,update_manywrites nothing),require_if_match=True, integer ids, adependencies=guard, and the store never being asked to write after a validation failure.- The OpenAPI document has
booksBatchGetwith a repeatedidsquery parameter andbooksBatchUpdatewith therequestsitem schema, and both list their problem responses.
S12.1.5 — Documentation and release notes
State: Closed (2026-10-04)
Acceptance:
- The API conventions' §17 gains the
:batchGetand:batchUpdaterules and names each new case id beside its rule. §19 no longer says the two are built when a consumer needs them. - Both framework packages' transfer guides show each method. The reference pages list the new symbols.
CHANGELOG.mdentries exist forrn-forge-web,rn-forge-djangoandrn-forge-fastapi.- The root and package sites build under
--strict, and the scaffold suite passes.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
for sym in InvalidBatchGet batch_get_ids BatchUpdateItem parse_batch_update check_item_precondition; do
grep -q "\"$sym\"" packages/rn-forge-web/src/rn_forge/web/__init__.py # S12.1.1
done
(cd packages/rn-forge-web && uv run pytest -q tests/test_transfer.py tests/test_concurrency.py tests/test_conformance.py) # S12.1.1, S12.1.2
grep -q 'transfer.batch-update-applies-each-merge-patch' packages/rn-forge-web/src/rn_forge/web/conformance/_transfer.py # S12.1.2
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py # S12.1.2
for sym in BatchGetMixin BatchUpdateMixin; do
grep -q "class $sym" packages/rn-forge-django/src/rn_forge/django/drf/transfer.py # S12.1.3
done
(cd packages/rn-forge-django && uv run pytest -q tests/drf tests/test_conformance.py) # S12.1.3
for fn in batch_get_router batch_update_router; do
grep -q "def $fn" packages/rn-forge-fastapi/src/rn_forge/fastapi/transfer.py # S12.1.4
done
absent '@app\.(get|post)\("/conformance/(capped-)?books:' packages/rn-forge-fastapi/tests/test_conformance.py # S12.1.4
(cd packages/rn-forge-fastapi && uv run pytest -q tests/test_transfer.py tests/test_conformance.py) # S12.1.4
uv run pyright # S12.1.1, S12.1.3, S12.1.4
uv run lint-imports # S12.1.1, S12.1.3, S12.1.4
absent 'built when a consumer needs them' packages/rn-forge-web/docs/guides/api-conventions.md # S12.1.5
for pkg in web django fastapi; do
grep -qi 'batchGet' "packages/rn-forge-$pkg/CHANGELOG.md" # S12.1.5
(cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S12.1.5
done
uv run pytest -q -m scaffold # S12.1.5
Considered and rejected
POST :batchGetwith the ids in a body. It escapes URL length limits, but AIP-231 makes the method aGET, and aGETis cacheable and safe to retry. The row cap keeps the URL short.- AIP-234's per-item
updateMask. §10 rejects field masks for updates. A merge patch per item keeps one partial-update language acrossPATCHand:batchUpdate. PUTsemantics per item (full replacement). A UI that edits several rows sends only the changed members, which is what a merge patch expresses.- Partial success with a per-item status list. Every existing batch method is all or nothing. A mixed outcome would need a second response shape and client logic to reconcile it.