F12.15 — FastAPI resource operations
| State | Closed |
| Parent | E12 |
| Iteration | Release 3 |
| Start Date | 2026-10-04 |
| Closed Date | 2026-10-04 |
| Predecessors | — |
| Source | Owner request, 2026-09-28 |
Stories: 5 Closed
| Story | State | Depends on |
|---|---|---|
S12.15.1 — Shared transfer rules in rn-forge-web |
Closed (2026-10-04) | — |
| S12.15.2 — Conformance cases | Closed (2026-10-04) | — |
S12.15.3 — rn-forge-django adopts the shared rules |
Closed (2026-10-04) | — |
| S12.15.4 — FastAPI route factories | Closed (2026-10-04) | — |
| S12.15.5 — Documentation and release notes | Closed (2026-10-04) | — |
rn-forge-django ships four mixins in rn_forge.django.drf.transfer
(ResourceExportMixin, ResourceImportMixin, BatchCreateMixin,
BatchDeleteMixin). A viewset gets export, :import, :importTemplate,
:batchCreate and :batchDelete by listing them. rn-forge-fastapi's
rn_forge.fastapi.transfer has only the building blocks (tabular_format,
tabular_response, read_rows, problem_response). Every FastAPI application
therefore writes those five handlers itself, including the conformance driver.
tests/test_conformance.py hand-writes /conformance/orders:import,
:batchCreate and :batchDelete, which its own docstring treats as a missing
adapter ("if a case needs more than a line or two over them, the adapter is
missing"). :importTemplate has neither a FastAPI helper nor a conformance case
on either stack.
This feature adds route factories that match the Django mixins one for one. It
moves the wire rules that the two stacks now word differently into
rn-forge-web, and adds the conformance cases that pin them.
Context
Outcome: a browser client's resource screen needed a FastAPI backend for
every row of the resource standards; the client's work did not gate this feature
(ADR-0008). It released with
F12.14, so one rn-forge-fastapi tag covered the whole
table.
Design
Outcome: the factories add no wire decision: wording the two stacks differed
on moved into rn-forge-web, because a client must not be able to tell the
stacks apart (ADR-0001 rule 5). Persistence is the
application's, through structural async store protocols that own the
transaction, so rn-forge-fastapi imports no ORM; there is one factory per
operation, as Django has one mixin per operation.
The FastAPI surface
Outcome: rn_forge.fastapi.transfer holds the store protocols and route
factories; the
FastAPI transfer guide shows
them and the
transfer reference lists
them.
New conformance cases
Outcome: the cases are in CASES, in the transfer area, documented in the
conformance reference; the
API conventions §17 name them
beside their rules.
Out of scope
- Partial-save import. Django's
import_rollback_on_validation_errors = Falsecommits the valid rows and returns 200 with anerrorslist. The FastAPI import is all-or-nothing only, until an application asks for more. - Large-file import as a long-running operation. This is the pattern in §17
(
POST /imports→ 202). It stays unbuilt on both stacks. :batchGetand:batchUpdate. These remain F12.1, with its own trigger.- A store implementation shipped by
rn-forge-sqlalchemy. The guide shows one in application code. Shipping it waits for a second FastAPI application that writes the same store.
S12.15.1 — Shared transfer rules in rn-forge-web
State: Closed (2026-10-04)
Acceptance:
rn_forge.web.transfergains the following, each re-exported fromrn_forge.web:ImportCounts, a frozen dataclass ofcreated,updatedandskipped.parse_flag(value), which isTrueonly for"true"or"1", case-insensitively, andFalsefor anything else, includingNone. It is the one parser forvalidateOnlyandprefill.row_cap_problem(kind, cap, *, instance, registry=None), wherekindis"import"or"batch". It renders a 422validation-errorwith detailThe {kind} exceeds the limit of {cap} rows.and noerrorsmember, alongside the existingexport_cap_problem.NON_EMPTY_LIST_DETAIL = "A non-empty list is required.".unsupported_file_detail(formats), which returnsUnsupported file type; use one of: csv, xlsx.for("csv", "xlsx").unreadable_file_detail(extension), which returnsThe file could not be read as csv.for"csv".
rn_forge.web.exceptionsgains two exceptions, both registered indefault_registry()and both implementingHasProblemExtensions:RowsInvalid(errors, *, root="rows"). It renders exactly asrow_errors_problem(errors, root=root)does: 422, detailOne or more rows are invalid., anderrors[].pointer = /<root>/<row>[/<field>].ItemsDenied(errors, *, root), aPermissionDeniedsubclass. It renders a 403forbiddenwith detailForbiddenanderrors[].pointer = /<root>/<index>[/<field>]. That is the bodyrn-forge-djangoproduces today forPermissionDenied({"requests": {"1": [message]}}).
tests/test_transfer.pycovers each new function and both exceptions' rendered bodies.uv run pyrightanduv run lint-importspass.
S12.15.2 — Conformance cases
State: Closed (2026-10-04)
Acceptance: rn_forge.web.conformance.CASES gains the cases in
New conformance cases, in the transfer area. Both
drivers run every case with no skips.
test_the_fixture_serves_every_path_the_table_uses passes on FastAPI with the
new paths.
S12.15.3 — rn-forge-django adopts the shared rules
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.drf.transferchanges as follows:- It uses
parse_flagforvalidateOnlyandprefill. - It uses
row_cap_problemfor the import and batch caps, in place of today'sValidationError, which renders anerrorsentry with an empty pointer. - It uses
unsupported_file_detailandunreadable_file_detailfor thefilefield. - It answers a missing
filepart withREQUIRED_FIELD_DETAILin place ofNo file was submitted..
- It uses
_list_memberanswers a missing member withREQUIRED_FIELD_DETAIL, and an empty list or a non-list withNON_EMPTY_LIST_DETAIL. Both carry the pointer/<key>.- The Django conformance fixture adds three things:
validate_batch_create_itemdenies an item namedforbiddenwithYou may not create this order.;/conformance/capped:importand/conformance/capped:batchCreaterun under aMAX_ROWSof 1; and the new cases pass. - The existing
tests/drf/transfer tests are updated for the changed details and pass.
S12.15.4 — FastAPI route factories
State: Closed (2026-10-04)
Acceptance:
rn_forge.fastapi.transfer(thetransferextra, still not imported byrn_forge.fastapi) gains the store protocols and route factories in The FastAPI surface, with the behavior its tables state. Every factory returns anAPIRouterand takesdependencies=likeAPIRouterdoes. Each store is obtained throughDepends(store), so a store dependency can take a session, a principal or filter query parameters.RowsResultgainstotal: int, the number of data rows read.read_rowsraisesValueErrorwithunsupported_file_detail(("csv", "tsv", "xlsx"))orunreadable_file_detail(extension).- The OpenAPI document of an app that includes the four routers for
/ordershas these properties:- The operationIds are
ordersImport,ordersImportTemplate,ordersBatchCreateandordersBatchDelete. :import's request body ismultipart/form-datawith a binaryfile.:batchCreate's request body is{"requests": [<model>]}, and its 200 response is{"<resource_name>": [<response_model>]}.:batchDelete's request body is{"ids": [string | integer]}, and it responds 204.FastApiApp's problem repair adds the 403, 404 and 422 responses it can produce.
- The operationIds are
tests/test_transfer.pycovers each factory's rows in the tables below. Those include the cases no conformance case reaches: an unsupported and an unreadable file, a store raisingRowsInvalid,ItemsDeniedfromdelete_many, integer ids, adependencies=guard, and the store never being called after a validation failure.- The FastAPI conformance fixture serves
/conformance/orders:import,:importTemplate,:batchCreate,:batchDeleteand the/conformance/capped:*routes through these factories over one in-memory store class. It serves its export routes throughtabular_export. No hand-written handler for these paths is left intests/test_conformance.py, and the file passes.
S12.15.5 — Documentation and release notes
State: Closed (2026-10-04)
Acceptance:
rn-forge-fastapi's transfer guide is rewritten around the factories. It shows a complete resource that uses a SQLAlchemy store built onrn-forge-sqlalchemy'supsertandkeyset, joined in application code because neither package imports the other. It also shows how a store enforces all-or-nothing in its own transaction.- The reference page for
rn_forge.fastapi.transferlists the new symbols.rn-forge-web's reference gains the newtransferand exception symbols. - The API conventions' §17 names every new conformance case id beside the rule it proves, and states the shared details (the caps, the missing file, the empty list and the denied item).
CHANGELOG.mdentries exist forrn-forge-web,rn-forge-fastapiandrn-forge-django. Django's entry lists each changed response detail.- The root and package sites build under
--strict. The scaffold suite (uv run pytest -m scaffold) passes, so the new cases also run from built wheels.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
for sym in ImportCounts parse_flag row_cap_problem RowsInvalid ItemsDenied NON_EMPTY_LIST_DETAIL; do
grep -q "\"$sym\"" packages/rn-forge-web/src/rn_forge/web/__init__.py # S12.15.1
done
(cd packages/rn-forge-web && uv run pytest -q tests/test_transfer.py tests/test_conformance.py) # S12.15.1, S12.15.2
grep -q 'importTemplate' packages/rn-forge-web/src/rn_forge/web/conformance/cases.py # S12.15.2
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py # S12.15.2
absent 'No file was submitted' packages/rn-forge-django/src # S12.15.3
grep -q 'row_cap_problem' packages/rn-forge-django/src/rn_forge/django/drf/transfer.py # S12.15.3
(cd packages/rn-forge-django && uv run pytest -q tests/drf tests/test_conformance.py) # S12.15.3, S12.15.5
for fn in import_router import_template_router batch_create_router batch_delete_router tabular_export; do
grep -q "def $fn" packages/rn-forge-fastapi/src/rn_forge/fastapi/transfer.py # S12.15.4
done
absent '@app\.(post|get)\("/conformance/(orders|capped):' packages/rn-forge-fastapi/tests/test_conformance.py # S12.15.4
(cd packages/rn-forge-fastapi && uv run pytest -q tests/test_transfer.py tests/test_conformance.py) # S12.15.4, S12.15.5
uv run pyright # S12.15.1, S12.15.4
uv run lint-imports # S12.15.1, S12.15.4
for pkg in web django fastapi; do
grep -qi 'importTemplate\|batch\|transfer' "packages/rn-forge-$pkg/CHANGELOG.md" # S12.15.5
(cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S12.15.5
done
uv run pytest -q -m scaffold # S12.15.5
Considered and rejected
- One
resource_router()taking every operation's options. One factory per operation matches Django's mixins, keeps each signature small, and lets an application mount only what it offers. - Callbacks in place of store dependencies. A plain callback cannot declare
FastAPI dependencies, so it could not get a session, a principal or filter
parameters without application glue. A store obtained through
Dependsgets them the ordinary FastAPI way. - Store protocols in
rn-forge-web. They mention pydantic models and FastAPI's dependency style, and nothing outside FastAPI uses them. Because they are structural, a store elsewhere can satisfy them without importing them.