fix: [Access API] update the device identification section in info.description by jimfengjinhua · Pull Request #146 · camaraproject/DedicatedNetworks

jimfengjinhua · 2026-08-01T10:33:26Z

What type of PR is this?

correction

What this PR does / why we need it:

Rewrite the "Identifying the device from the access token" section to accurately describe behavior for both two-legged and three-legged access tokens, and align error handling descriptions with the CAMARA common definitions of MISSING_IDENTIFIER and UNNECESSARY_IDENTIFIER.

Which issue(s) this PR fixes:

Fixes #144

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

… token types Rewrite the "Identifying the device from the access token" section to accurately describe behavior for both two-legged and three-legged access tokens, and align error handling descriptions with the CAMARA common definitions of MISSING_IDENTIFIER and UNNECESSARY_IDENTIFIER.

Co-authored-by: tlohmar <Thorsten.Lohmar@ericsson.com>

hdamker

The MISSING_IDENTIFIER / UNNECESSARY_IDENTIFIER swap from #144 is fixed, and now matches the Commonalities canonical template (identifying-device-from-access-token) word for word for those two bullets.

But copying the canonical text as-is doesn't quite fit here: the template assumes a single device field, but this API identifies devices via a devices array (CreateAccessRequest.devices), and for add/remove the array is the request body with no field wrapper at all. A few lines still say "the device object", which doesn't correspond to anything in the schema. Suggested line-level adaptations below — happy to have these adjusted rather than taken as-is.

hdamker · 2026-08-06T08:20:57Z

    This API requires the API consumer to identify a device as the subject of the API as follows:
-    - Since this API can handle multiple devices in one request it is strongly recommended to use a two-legged access token
-    - When the API is invoked using a two-legged access token, each device will be identified by the respective `device` identifier, which therefore MUST be provided.
+    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.


Suggested change

- When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.

- When the API is invoked using a two-legged access token, the subject(s) will be identified from the device(s) provided in the request, which therefore MUST be provided.

Suggested change

- When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.

- When the API is invoked using a two-legged access token, the subject(s) will be identified from the `device` object(s) provided in the request, which therefore MUST be provided.

keeping the style of device

hdamker · 2026-08-06T08:21:00Z

+    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.
+    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.
+
+    Since this API can handle multiple devices in one request, it is strongly recommended to use a two-legged access token.


It is a consequence from the design, not really a recommendation:

Suggested change

Since this API can handle multiple devices in one request, it is strongly recommended to use a two-legged access token.

Because a three-legged access token identifies exactly one device (from the token itself) and does not allow an explicit device list, a two-legged access token MUST be used whenever a request includes multiple devices.

hdamker · 2026-08-06T08:23:08Z

    ## Error handling:

-    - If the subject can be identified from the access token and there is no matching `device` object, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
+    - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.


Suggested change

- If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

- If the subject cannot be identified from the access token and no device is included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

hmm, why not following L95 of the info.description template?

hdamker · 2026-08-06T08:28:59Z

-    - Since this API can handle multiple devices in one request it is strongly recommended to use a two-legged access token
-    - When the API is invoked using a two-legged access token, each device will be identified by the respective `device` identifier, which therefore MUST be provided.
+    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.
+    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.


Suggested change

- When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.

- When a three-legged access token is used however, a device MUST NOT be provided in the request, as the subject will be uniquely identified from the access token.

L87 uses this optional identifier, while a device is much clearer.

Might be good to fix this in the template as well.

L87 uses this optional identifier, while a device is much clearer.

Might be good to fix this in the template as well.

Actual it should be "the object devices MUST NOT be provided in the request".

In the template this sentence reads well in context, just not in isolation.

hdamker · 2026-08-06T08:33:54Z

Another observation which is maybe more critical: addDevicesToAccess (AddDevicesRequest) and removeDevicesFromAccess both require a non-empty
device list (minItems: 1) regardless of token type, but line 31 says correctly a three-legged token forbids
providing any device explicitly. As written, a three-legged token can never be used to add or remove
devices. I would say that especially addDevicesToAccess should be able to be used with a single device identified by the token.

hdamker · 2026-08-06T08:45:56Z

-    - If the subject can be identified from the access token and there is no matching `device` object, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
+    - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
+
+    - If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.


One line I missed in my review above:

Suggested change

- If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

- If the subject can be identified from the access token and one or more devices are also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

Good point.
Rephrasing to keep the style of object

Suggested change

- If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

- If the subject can be identified from the access token and the one or more `device` objects are also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

hdamker · 2026-08-06T17:46:23Z

@tlohmar thanks for your comments. As said, feel free to adjust, not expected that the suggestions will be taken as-is. Just that the template does not fit fully.

tlohmar · 2026-08-07T12:00:11Z

@hdamker @jimfengjinhua it could be simpler to not support the usage of three-legged access tokens (instead of fixing the operations with one device only).

jimfengjinhua requested review from PeterKovacs2, carlosromerog, eric-murray and tlohmar as code owners August 1, 2026 10:33

tlohmar reviewed Aug 5, 2026

View reviewed changes

Comment thread code/API_definitions/dedicated-network-accesses.yaml Outdated

tlohmar reviewed Aug 5, 2026

View reviewed changes

Comment thread code/API_definitions/dedicated-network-accesses.yaml Outdated

tlohmar reviewed Aug 5, 2026

View reviewed changes

Comment thread code/API_definitions/dedicated-network-accesses.yaml Outdated

jimfengjinhua and others added 3 commits August 5, 2026 15:52

Update code/API_definitions/dedicated-network-accesses.yaml

a6b0eac

Co-authored-by: tlohmar <Thorsten.Lohmar@ericsson.com>

Update code/API_definitions/dedicated-network-accesses.yaml

c8c153e

Co-authored-by: tlohmar <Thorsten.Lohmar@ericsson.com>

Update code/API_definitions/dedicated-network-accesses.yaml

27d02cf

Co-authored-by: tlohmar <Thorsten.Lohmar@ericsson.com>

jimfengjinhua mentioned this pull request Aug 6, 2026

[Accesses API] 422 MISSING_IDENTIFIER condition in info.description contradicts the error code definition #144

Open

hdamker reviewed Aug 6, 2026

View reviewed changes

tlohmar requested a review from SteveV-Vodafone August 6, 2026 13:25

	- When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.
	- When the API is invoked using a two-legged access token, the subject(s) will be identified from the device(s) provided in the request, which therefore MUST be provided.

	Since this API can handle multiple devices in one request, it is strongly recommended to use a two-legged access token.
	Because a three-legged access token identifies exactly one device (from the token itself) and does not allow an explicit device list, a two-legged access token MUST be used whenever a request includes multiple devices.

	- If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
	- If the subject cannot be identified from the access token and no device is included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

	- When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.
	- When a three-legged access token is used however, a device MUST NOT be provided in the request, as the subject will be uniquely identified from the access token.

	- If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.
	- If the subject can be identified from the access token and one or more devices are also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.

Uh oh!

Conversation

jimfengjinhua commented Aug 1, 2026

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hdamker left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hdamker commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hdamker Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hdamker commented Aug 6, 2026

Uh oh!

tlohmar commented Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hdamker left a comment •

edited

Loading

hdamker commented Aug 6, 2026 •

edited

Loading

hdamker Aug 6, 2026 •

edited

Loading