[mike-gorman-bitwarden]

🎟️ Tracking

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

📔 Objective

Adds ADR-0044, "API standards for updating and deleting resources", with status Proposed. Sets how resources are updated and deleted: PUT with complete replacement, partial updates (discouraged; RFC 7396 semantics with a recorded departure on empty strings), optimistic concurrency with a version field and 409 (with the recorded departure from conditional requests), and hard and soft deletes.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	e15d912
Status:	✅  Deploy successful!
Preview URL:	https://3cccee2a.contributing-docs.pages.dev
Branch Preview URL:	https://docs-adr-0044-api-standards.contributing-docs.pages.dev

View logs

[rkac-bw]

From the database side:

1. version: an integer that changes on every update matches what we would store (BIGINT, incremented in the same statement as the update). Supportive.
2. Soft deletes need a purge horizon. A service that soft-deletes should state how long deleted rows are kept before a hard delete, and who runs the purge. Otherwise deleted data accumulates indefinitely, which is a storage cost and, for user data, a deletion-obligation question.
3. Uniqueness under soft delete. Worth one line: a unique constraint must exclude soft-deleted rows (a filtered unique index), or a deleted resource blocks re-creating one with the same name or email.

[mike-gorman-bitwarden]

Thanks.

1. Good to hear.
2. Agreed that a service with soft deletes needs a retention period and a purge, but that's that service's retention policy, not part of the API contract. Callers can always ask for permanent=true.
3. How a service enforces uniqueness, and whether a soft-deleted resource blocks re-creating one, is up to the owning service. A filtered unique index is a good way to do it.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This reviews the new ADR-0044 (status Proposed), which sets standards for updating resources (PUT, plus PATCH for partial updates, which it discourages), for optimistic concurrency (a version field and 409), and for hard and soft deletes. The frontmatter, the AdrTable usage, and the section structure match ADR-0036 and the MADR template, and the claims made about RFC 9110 and RFC 7396 are accurate. One question is open: how a required version works with create-or-update PUT and with partial updates. ADR-0039, ADR-0040 and ADR-0045 are mentioned in plain text and are not on main yet, so they create no broken links.

Code Review Details

• ❓ : How a required version and the 409-on-mismatch rule apply to a creating PUT and to PATCH
  • docs/architecture/adr/0044-api-standards-for-updating-and-deleting-resources.md:78-82

[mike-gorman-bitwarden]

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