Skip to content

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 = False commits the valid rows and returns 200 with an errors list. 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.
  • :batchGet and :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.transfer gains the following, each re-exported from rn_forge.web:
    • ImportCounts, a frozen dataclass of created, updated and skipped.
    • parse_flag(value), which is True only for "true" or "1", case-insensitively, and False for anything else, including None. It is the one parser for validateOnly and prefill.
    • row_cap_problem(kind, cap, *, instance, registry=None), where kind is "import" or "batch". It renders a 422 validation-error with detail The {kind} exceeds the limit of {cap} rows. and no errors member, alongside the existing export_cap_problem.
    • NON_EMPTY_LIST_DETAIL = "A non-empty list is required.".
    • unsupported_file_detail(formats), which returns Unsupported file type; use one of: csv, xlsx. for ("csv", "xlsx").
    • unreadable_file_detail(extension), which returns The file could not be read as csv. for "csv".
  • rn_forge.web.exceptions gains two exceptions, both registered in default_registry() and both implementing HasProblemExtensions:
    • RowsInvalid(errors, *, root="rows"). It renders exactly as row_errors_problem(errors, root=root) does: 422, detail One or more rows are invalid., and errors[].pointer = /<root>/<row>[/<field>].
    • ItemsDenied(errors, *, root), a PermissionDenied subclass. It renders a 403 forbidden with detail Forbidden and errors[].pointer = /<root>/<index>[/<field>]. That is the body rn-forge-django produces today for PermissionDenied({"requests": {"1": [message]}}).
  • tests/test_transfer.py covers each new function and both exceptions' rendered bodies. uv run pyright and uv run lint-imports pass.

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.transfer changes as follows:
    • It uses parse_flag for validateOnly and prefill.
    • It uses row_cap_problem for the import and batch caps, in place of today's ValidationError, which renders an errors entry with an empty pointer.
    • It uses unsupported_file_detail and unreadable_file_detail for the file field.
    • It answers a missing file part with REQUIRED_FIELD_DETAIL in place of No file was submitted..
  • _list_member answers a missing member with REQUIRED_FIELD_DETAIL, and an empty list or a non-list with NON_EMPTY_LIST_DETAIL. Both carry the pointer /<key>.
  • The Django conformance fixture adds three things: validate_batch_create_item denies an item named forbidden with You may not create this order.; /conformance/capped:import and /conformance/capped:batchCreate run under a MAX_ROWS of 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 (the transfer extra, still not imported by rn_forge.fastapi) gains the store protocols and route factories in The FastAPI surface, with the behavior its tables state. Every factory returns an APIRouter and takes dependencies= like APIRouter does. Each store is obtained through Depends(store), so a store dependency can take a session, a principal or filter query parameters.
  • RowsResult gains total: int, the number of data rows read. read_rows raises ValueError with unsupported_file_detail(("csv", "tsv", "xlsx")) or unreadable_file_detail(extension).
  • The OpenAPI document of an app that includes the four routers for /orders has these properties:
    • The operationIds are ordersImport, ordersImportTemplate, ordersBatchCreate and ordersBatchDelete.
    • :import's request body is multipart/form-data with a binary file.
    • :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.
  • tests/test_transfer.py covers each factory's rows in the tables below. Those include the cases no conformance case reaches: an unsupported and an unreadable file, a store raising RowsInvalid, ItemsDenied from delete_many, integer ids, a dependencies= guard, and the store never being called after a validation failure.
  • The FastAPI conformance fixture serves /conformance/orders:import, :importTemplate, :batchCreate, :batchDelete and the /conformance/capped:* routes through these factories over one in-memory store class. It serves its export routes through tabular_export. No hand-written handler for these paths is left in tests/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 on rn-forge-sqlalchemy's upsert and keyset, 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.transfer lists the new symbols. rn-forge-web's reference gains the new transfer and 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.md entries exist for rn-forge-web, rn-forge-fastapi and rn-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 Depends gets 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.