docs: Add ADR 0043 - API standards for reading resources

[mike-gorman-bitwarden]

🎟️ Tracking

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

📔 Objective

Adds ADR-0043, "API standards for reading resources", with status Proposed. Sets how resources are read: reading one and many, filter[...] parameters, multi-value parameters and ranges with their escaping rules, sort, sparse fieldsets, offset and cursor paging, and advanced queries through a :search operation using a restricted subset of JSON Logic.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	e2a58a8
Status:	✅  Deploy successful!
Preview URL:	https://2cf07ba9.contributing-docs.pages.dev
Branch Preview URL:	https://docs-adr-0043-api-standards.contributing-docs.pages.dev

View logs

[rkac-bw]

From the database side, four additions:

1. A maximum page[size] that every read-many API documents in OpenAPI, the way ADR-0046 already requires a documented maximum for bulk items. Without one, a caller can ask for an unbounded page.
2. totalCount and pageCount optional, or allowed to be approximate, for offset paging. As written they are a MUST, which means a COUNT over the filtered set on every page request. That is cheap on small collections and expensive on large ones (events, ciphers, members of large organizations).
3. Contains-matching (*mi*) only on fields the API marks as supporting it. A leading wildcard cannot use an index, so it scans. ADR-0041 already requires OpenAPI to say which attributes can be filtered and sorted; please extend that to say which support prefix or contains matching.
4. :search with arbitrary and/or should compile to parameterised SQL of bounded shape. Free-form expressions otherwise produce a different query plan per combination, which crowds the plan cache and makes performance unpredictable. A sentence that the service may reject expressions it cannot serve efficiently (422) would cover it.

[mike-gorman-bitwarden]

Thanks, these were useful. Changes in e2a58a8:

1. Maximum page[size]: paged APIs now MUST document a maximum page[size]. No separate rejection rule is needed: ADR-0040's request validation already requires declared maximum values to be respected, so an oversized page is rejected with 422.
2. Offset totals: pageCount and totalCount are now SHOULD. pageNumber and pageSize stay MUST. Large collections can also use cursor paging, which carries no totals.
3. Wildcards: you're right that this was missing. The rule used to require every API with wildcards to support starts-with, ends-with, and contains. It now says APIs that support * MUST document which attributes accept it. On any other attribute * is just a literal character, so it can't trigger a leading-wildcard scan.
4. :search: no change here. Lines 158–159 already require rejecting, with 422, any operator outside the allowed subset and any field the API doesn't support. How a service turns a query into SQL is up to that service, so the standard doesn't prescribe it.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: REQUEST CHANGES

This PR adds ADR-0043, which sets the standards for reading resources: filtering, multi-value parameters and ranges, sorting, sparse fieldsets, offset and cursor paging, and the :search operation. The frontmatter and MADR structure follow the ADR template, and commit e2a58a8 addresses the database feedback. One problem remains: the escaping rules don't say how to match a literal asterisk on a single-value parameter that supports wildcards.

Code Review Details

• ⚠️ : Asterisk and backslash escaping only applies to multi-value and range parameters, so a single-value wildcard parameter can't match a literal *. Making a parameter multi-value also changes what a backslash means.
  • docs/architecture/adr/0043-api-standards-for-reading-resources.md:77-81