[mike-gorman-bitwarden]

🎟️ Tracking

Follow-up to ADR-0036 (#865).

📔 Objective

Adds ADR-0046, "API standards for bulk processing resources", with status Proposed. Sets how many resources are created, updated, replaced, deleted, or acted upon in one request: :bulk-* operations, targeting by data, ids, or filter, single-resource rules applied per resource, all-or-nothing or best-effort atomicity, synchronous or asynchronous execution, and the response format.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	e212797
Status:	✅  Deploy successful!
Preview URL:	https://5a114d31.contributing-docs.pages.dev
Branch Preview URL:	https://docs-adr-0046-api-standards.contributing-docs.pages.dev

View logs

[rkac-bw]

From the database side:

1. All-or-nothing is one database transaction across every item. Please tie the documented maximum item count to that: a large all-or-nothing request holds locks and log for its whole duration, and once one statement holds about 5,000 locks on a table, SQL Server tries to escalate to a table lock. Suggest synchronous all-or-nothing is bounded (for example at most a few hundred items), and larger sets go asynchronous.
2. filter targeting has no item count until it runs. The "too many items" check can only apply to ids and data. A filter-targeted bulk update or delete should either be capped (reject when the filter matches more than the maximum) or be asynchronous by default.
3. Supportive of allowing a set-based implementation, provided per-resource side effects are kept. With an outbox, that means one outbox row per changed resource, in the same transaction.

[mike-gorman-bitwarden]

Thanks.

On 1 and 2: I'm reluctant to make the standards prescriptive about the limits an API may support. They shouldn't assume what kind of database is behind the API, and what's hard for one store can be trivial for another. A filter-targeted update of 100,000 well-indexed rows may be perfectly fine on one, for example. So the ADR flags the trade-off and leaves the numbers to the service owner: each API documents its maximum (Targeting), a service can respond asynchronously above a documented size, and the Execution section says when synchronous or asynchronous fits best. Your lock-escalation point is exactly the kind of thing an owner on SQL Server should weigh when setting those numbers.

On 3: agreed. Lines 82–83 require the same side effects for each resource, and one outbox row per changed resource is a good way to meet that.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR adds one documentation file: ADR-0046, "API standards for bulk processing resources", with status Proposed. Its frontmatter and structure match ADR-0036 and the MADR template, and I found no internal contradictions in the targeting, atomicity, execution, or response rules. ADR-0039, 0043, 0044, and 0045 are referenced as plain text rather than links, so the fact that they are not yet on main does not create broken links. There is one suggestion: make the documented maximum item count an explicit requirement.

Code Review Details

• 🎨 : The 422 rule for oversized requests depends on a "documented maximum", but no rule requires an API to document one
  • docs/architecture/adr/0046-api-standards-for-bulk-processing.md:69

[mike-gorman-bitwarden]

This PR is superseded by #894. We have done our best to retain/incorporate all feedback received to date.