Skip to content

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_missing upsert and partial results. Both batch methods stay all or nothing, as :batchCreate and :batchDelete are.
  • readMask on :batchGet. F12.9 adds it.

S12.1.1 — Shared batch rules in rn-forge-web

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.web exports InvalidBatchGet, batch_get_ids, NON_EMPTY_IDS_DETAIL, DUPLICATE_ID_DETAIL, BatchUpdateItem, parse_batch_update and check_item_precondition, with the contracts in Shared pieces.
  • PreconditionRequired, MalformedPrecondition and VersionConflict accept an optional errors argument. Without it, their rendered bodies are unchanged; every existing concurrency case still passes.
  • tests/test_transfer.py and tests/test_concurrency.py cover each new function: every step of both tables, ids given as strings or integers, empty ids values dropped, and * as an item's ifMatch.

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.transfer exports BatchGetMixin and BatchUpdateMixin, served by CustomMethodRouter at {collection}:batchGet and {collection}:batchUpdate.
  • The Django conformance fixture serves /conformance/books and /conformance/capped-books through them, and the new cases pass.
  • tests/drf/ covers what the cases do not reach: validate_batch_update_item denying an item (403, nothing written), batch_update_requires_if_match (428 with the pointer), audit fields set on every updated row, an unversioned model ignoring ifMatch, and a filter_queryset scope hiding an id (404), and an id the key cannot hold (404, also for :batchDelete).
  • The drf-spectacular schema names the operations booksBatchGet and booksBatchUpdate.

S12.1.4 — FastAPI binding

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.fastapi.transfer exports BatchGetStore, BatchUpdateStore, batch_get_router and batch_update_router.
  • The FastAPI conformance fixture serves /conformance/books and /conformance/capped-books through them over an in-memory store, with no hand-written handler for those paths, and the new cases pass.
  • tests/test_transfer.py covers a store raising ItemsDenied (403, update_many writes nothing), require_if_match=True, integer ids, a dependencies= guard, and the store never being asked to write after a validation failure.
  • The OpenAPI document has booksBatchGet with a repeated ids query parameter and booksBatchUpdate with the requests item 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 :batchGet and :batchUpdate rules 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.md entries exist for rn-forge-web, rn-forge-django and rn-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 :batchGet with the ids in a body. It escapes URL length limits, but AIP-231 makes the method a GET, and a GET is 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 across PATCH and :batchUpdate.
  • PUT semantics 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.