Enhancement to support managing multiple devices per Device Access

[hubertp-ericsson]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

This PR proposes enhancement of the Accesses API to enable handling of more than one device per Device Access. It addresses issue #70 by adding a separate device group handling endpoint and a new device group identifier. The device group identifier is used when providing device access to Dedicated Network. The device group referred to by the identifier can be used by more than one Device Access at the same time or at different times (i.e. identified by different accessId identifiers), and can therefore be reused multiple times. Devices can be added and/or removed from a device group while being used be a Device Access affecting their respective rights to access the Dedicated Network.

Which issue(s) this PR fixes:

Fixes #70

Special notes for reviewers:

Changelog input

 Enhancement to support managing multiple devices per Device Access.

Additional documentation

This section can be blank.

docs

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: hubertp-ericsson / name: Hubert Przybysz (2fd5336, 38144a1, a6c0c1c)

[hdamker]

@camaraproject/application-profile_codeowners that PR is too large to be incorporated last minute into the Fall25 release, so I suppose it is planned for the next release. Please set to draft to provide release reviewers a clear situation.

[hdamker]

/easycla

[sergiobrisio]

I have some concerns on this pull request, I will express in the following comments:

1. Dual Provisioning Paths risks:
   With both individual and group-based APIs for POST, DELETE, and just group based for PATCH, we risk creating two parallel models that can diverge.
   Example A: If a device belongs to a group but its access is later modified individually, the group could become inconsistent.
   Example B: I have created a group ID, and I patch a group ID deleting a device access and then I newly add the same device to that access with the individual endpoint, would/could it be again inside the group? does the access still reference the group or not?
   Example C: If I create a group A and then I want to create a group B but one or more devices belongs to both (not null intersection case), what should happen? Overlapping groups may create unclear precedence...

Notes 11/3/2025:
if an /accesses/{id} created with a deviceGroupId maintains a live reference to the group membership (with an additional property provisioningMode = individual/group), we have to forbid per‑device mutations on accesses (o require a detach from group at first) when we have that property set to group (provisioningMode=group).
Deleting a device in a referenced group must be performed via /device-groups/{deviceGroupId}; attempts to delete the per‑device access directly return 409 RESOURCE_IN_USE

We have also to define a behavior for overlapping groups: (A) prevent a device from being concurrently in two active group‑bound accesses for the same networkId (B) manage union of multiple accesses (couldn't be too complex?!)

[sergiobrisio]

2. Provenance and Auditability
   The basic idea is that CSP or ASP for auditing/accountability/security purposes must tell how an access was created and by whom, without scraping DB logs (i.e. relying solely on backend DB for reporting and troubleshooting)

Example: ASP API consumer 1 has provisioned a group of device with individual API endpoint, ASP API consumer 2 has provisioned a set of device with group API endpoint. After a while a third actor (could be in ASP or CSP) has to do an auditing on a wrong provisioning and he has no glue on which was the event to lookup in the logs...

The API could expose whether an access was created via group or individually (e.g., provisioningMode = individual|group, originGroupId) to avoid relying solely on backend DB for reporting and troubleshooting. Those info can be exposed in the GET /accesses response or can be introduced as query parmeters in the endpoint (GET /accesses?networkId=...&deviceGroupId=...&provisioningMode=group&originGroupId=...)

[sergiobrisio]

3. QoS Policy Invariant
   The specification states “resource usage can be tailored for each device within the constraints of the profile.”
   However, when introducing device groups, it is essential to clarify whether:
   A) Groups enforce uniform policies (all devices in the group share the same QoS/network settings),
   B) per-device overrides are allowed (individual devices in a group can have different settings).

Challenging example: Suppose a group is created and then, via PATCH, the QoS Profile or Network ID is changed for a specific device within that group. This could introduce complexity and ambiguity in managing device-to-network relationships.
It may also contradict the intent of treating the group as a cohesive management unit.

A uniform mode approach would mean that the group is intended as a cohesive management unit: all devices share defaultQosProfile and qosProfiles; per‑device PATCH operations on accesses created via group provisioning (provisioningMode=group) are forbidden.

If individualized management is required for a device, the correct process would be:

• remove the device from the group, for example with PATCH /device-groups/{deviceGroupId}
• then a further POST /accesses will allow to create a new individual access for the specific device.

[sergiobrisio]

Counting and Observability issue: with two separate POST endpoint, if I want to know how many devices are there with the specific Dedicated Network (so the instance of a DN with a specific Network ID) how can I count them?

I suggest to design, together with the current endpoints, a way to count devices per networkId and filter by deviceGroupId, provisioningMode, originGroupId, etc

Possible suggested counting endpoints:
GET /accesses?networkId=... with Prefer: count=exact and response header X-Total-Count
GET /accesses/stats?networkId= returning { "networkId": "...", "totalAccesses": 123, "byProvisioningMode": { "group": 90, "individual": 33 } }

[sergiobrisio]

Alternative Approach to new endpoint for group device access.

If the real need is bulk provisioning, you may consider extending the existing POST /accesses to accept multiple devices.
This could reduces complexity and avoids dual semantics, for example by allowing a simple array in the device section:
`POST /accesses
Content-Type: application/json
x-idempotency-key: 123e4567-e89b-12d3-a456-426614174000

{
"networkId": "b4333c46-49c0-4f62-80d7-f0ef930f1c46",
"devices": [
{ "phoneNumber": "" },
{ "networkAccessId": ""}
],
"defaultQosProfile": [...]`

Another alternative is introducing POST /accesses/batch instead of creating a new persistent resource type.

NOTE 3/11/2025
A well-designed API may go a bit further than exposing backend functionality: it could encode the consistency boundaries of the system. This is where concepts from software architecture, such as the “aggregate” in Domain Driven Design (DDD), become essential. In DDD, an aggregate is a cluster of related objects that are treated as a single unit for data changes. The aggregate root enforces all invariants and rules, ensuring that the system’s state remains consistent, even in the face of concurrent operations or partial failures.

APIs can be designed to reflect aggregate boundaries:

• making clear which operations are allowed and which are not (enforcing invariants “at the edge”).
• preventing “ghost state” (inconsistent or orphaned data that requires later reconciliation).
• providing reliable observability and auditability, because every change flows through a well-defined interface.
• reducing concurrency hazards, since all mutations to the aggregate go through a single, controlled entry point.

Treating a group of resources (in our case device accesses) as an aggregate means that the API exposes only the operations that make sense for the whole group. If a device needs any specific individual management, as shown in comment 1 above, it must first be removed from the group. This means that the APIs is mirroring the aggregate’s consistency boundary in the underlining software, making both implementation and client code simpler and potentially more concurrency-safe.

So together with this alternative approach , it could be beneficial for the API that we preserve consistency and the aggregate boundary by rejecting PATCH operations that attempt to modify per-device settings on accesses provisioned via a group (provisioningMode=group). This would help maintain clear and predictable behavior for both API consumers and implementers.

[hdamker]

Wouldn't it make sense to collaborate with the team of cos-booking-and-assignment and see if it is possible to find a common ground to design the assignment of a bulk of device with one request to a network (reservation)? I'm skeptical to introduce a complete new resource type for this purpose, especially if there is the requirement that devices can be managed individually further on.

[Kevsy]

Just to note that since CAMARA follows REST principles, we should use the established term 'collection' to refer to a group of resources ( ref "Architectural Styles and the Design of Network-based Software", R. Fielding, Section 5.2.1.1, 2000).

[hubertp-ericsson]

Just to note that since CAMARA follows REST principles, we should use the established term 'collection' to refer to a group of resources ( ref R. Fielding, "Architectural Styles and the Design of Network-based Software", R. Fielding, Section 5.2.1.1, 2000).

Thanks for your comment. Just to understand your comment, are you suggesting to use the term 'device-collection' in the API instead of 'device-group' ?

[Kevsy]

Just to note that since CAMARA follows REST principles, we should use the established term 'collection' to refer to a group of resources ( ref R. Fielding, "Architectural Styles and the Design of Network-based Software", R. Fielding, Section 5.2.1.1, 2000).

Thanks for your comment. Just to understand your comment, are you suggesting to use the term 'device-collection' in the API instead of 'device-group' ?

No, it's rather when discussing the concept - I suggest to use 'collection' rather than 'group of resources' or 'aggregate' , because it's the established term. The collection resource itself can be named whatever is deemed most suitable.