[mike-gorman-bitwarden]

🎟️ Tracking

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

📔 Objective

Adds ADR-0042, "API standards for creating resources", with status Proposed. Sets how resources are created: POST to the collection, omitting server-generated IDs, and 201/202/204 responses.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	efedc5f
Status:	✅  Deploy successful!
Preview URL:	https://032509e4.contributing-docs.pages.dev
Branch Preview URL:	https://docs-adr-0042-api-standards.contributing-docs.pages.dev

View logs

[rkac-bw]

Idempotency for create. Service clients will retry (bounded retries with backoff), and a retried POST that succeeded the first time creates a duplicate. Either an Idempotency-Key header with a stated retention window, or client-generated IDs through PUT create-or-update, would make creates retry-safe. The ADR currently says nothing about this.

[mike-gorman-bitwarden]

The standards already allow both forms of retry-safe create without a new header. Create-or-update through PUT with a client-chosen ID is covered (line 38, and ADR-0044), and PUT is idempotent. A POST can also carry a client-generated id, since id is only omitted when the service generates it, so a retry fails on the existing ID instead of creating a duplicate. Which creates need to be retry-safe is a decision for each API. I'd rather not adopt Idempotency-Key while it's still an IETF draft.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: REQUEST CHANGES

Reviewed the new ADR-0042 (docs/architecture/adr/0042-api-standards-for-creating-resources.md), which sets the method, path, request and success responses for creating resources. The frontmatter, tags and MADR structure follow the existing ADRs. ADRs 0039, 0040, 0044, 0045 and 0046 are cited in plain text without links; each one exists as a sibling branch in this series, so the docs build has no broken links. The idempotency discussion in the general comments already has a decision from the author and is not reopened here.

Code Review Details

• ⚠️ : No Location header is required. A 204 for a server-generated ID leaves the caller unable to find the new resource, and a 201 without Location points at the collection under RFC 9110 §15.3.2.
  • docs/architecture/adr/0042-api-standards-for-creating-resources.md:39-45

[mike-gorman-bitwarden]

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