Problem description
Across CAMARA sub-projects there is increasing demand to operate on large sets of resources (devices, areas, etc.), which is driving the proposal of a cross-cutting Group Management API (Commonalities issue #568 and an API Proposal in APIBacklog #288 )
However, CAMARA currently lacks Commonalities-level guidance to clearly distinguish between:
- Collections used for listing/pagination (representation concern, not a consistency boundary)
- Invariant-bearing Resource Groups (true consistency boundaries where cross-resource invariants must hold)
- Batch/bulk request patterns (single request to operate on many independent resources without persistent group semantics)
Without such guidance, new “group” or “bulk” capabilities risk introducing ambiguous semantics and backend complexity:
- overlap of groups causing conflicting policies, 1
- dual-write ambiguity (single-resource operations vs group-level operations) 2
- concurrency hazards when membership changes while fan-out operations execute, leading to ad-hoc reconciliation/locking/rollback logic in provider implementations.
- difficulties in managing Provenance and Auditability 3
This is especially relevant because the Group Management API proposal explicitly introduces fan-out operations, per-resource status reporting, and group identifiers used across multiple Service APIs—areas where consistency boundaries must be made explicit.
Possible evolution
Add a new section to CAMARA-API-Design-Guide.md clarifying “Collections vs Resource Groups (Consistency Boundaries) + Batch semantics”, including normative rules and examples:
- Collections are not consistency boundaries: listing/pagination must not be interpreted as transactional boundary.
- Batch vs Group distinction:
- If the need is only bulk execution (reduce number of requests), APIs MAY use batch request shapes (e.g., POST /accesses with devices[]) provided the spec explicitly defines:
- atomic vs partial success behavior,
- retry/idempotency strategy,
- per-item result/error reporting format (if partial success is allowed).
- If cross-resource invariants must hold, then APIs MUST model a Resource Group as a first-class resource and define:
- invariants enforced,
- overlap policy and deterministic conflict resolution,
- precedence rules for member-level mutation vs group-level constraints,
- concurrency model (e.g., snapshot membership for fan-out vs live membership),
- error semantics (409/412/422 etc.) and recommended concurrency control (ETag/If-Match).
- Event/subscription alignment
- any “new envelope” or per-resource status reporting for group fan-out MUST align with the existing CAMARA Event Subscription and Notification Guide patterns (subscription-started/updated/ended and error definition).
These proposed *Commonalities guidelines should be treated as a prerequisite baseline for the evolving Group Management API, to ensure consistent semantics across subprojects and avoid divergent implementations
Alternative solution
Proceed with Group Management API design without introducing the prerequisite guideline, letting each subproject implement its own group/bulk semantics.
Downside: high risk of inconsistent behavior across CAMARA APIs (different overlap rules, different precedence, different concurrency assumptions), which will increase implementation complexity for API providers and operational friction for API consumers.
Additional context
- The Group Management API proposal targets large-scale scenarios (e.g., Geofencing subscriptions, SIM Swap subscriptions, IoT fleet updates) and introduces asynchronous fan-out, per-resource results, and new notification patterns. This amplifies the need for explicit consistency-boundary guidance.
- The proposed guideline also benefits APIs that only need bulk onboarding (batch requests) without forcing creation of persistent group resources.
- This aligns with existing CAMARA documentation separation: the Event Subscription and Notification Guide already standardize event/subscription semantics; group-related fan-out reporting should integrate with it rather than introduce parallel patterns.
Problem description
Across CAMARA sub-projects there is increasing demand to operate on large sets of resources (devices, areas, etc.), which is driving the proposal of a cross-cutting Group Management API (Commonalities issue #568 and an API Proposal in APIBacklog #288 )
However, CAMARA currently lacks Commonalities-level guidance to clearly distinguish between:
Without such guidance, new “group” or “bulk” capabilities risk introducing ambiguous semantics and backend complexity:
This is especially relevant because the Group Management API proposal explicitly introduces fan-out operations, per-resource status reporting, and group identifiers used across multiple Service APIs—areas where consistency boundaries must be made explicit.
Possible evolution
Add a new section to CAMARA-API-Design-Guide.md clarifying “Collections vs Resource Groups (Consistency Boundaries) + Batch semantics”, including normative rules and examples:
These proposed *Commonalities guidelines should be treated as a prerequisite baseline for the evolving Group Management API, to ensure consistent semantics across subprojects and avoid divergent implementations
Alternative solution
Proceed with Group Management API design without introducing the prerequisite guideline, letting each subproject implement its own group/bulk semantics.
Downside: high risk of inconsistent behavior across CAMARA APIs (different overlap rules, different precedence, different concurrency assumptions), which will increase implementation complexity for API providers and operational friction for API consumers.
Additional context