docs: ambiguity in DeviceResponse description

[Kevsy]

Problem description

The 'DeviceResponse` object is described as follows:

An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the device parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.

If the API consumer provides more than one device identifier in their request, the API provider must return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.

It is not clear if the API provider may | should include the $.device property if only a single identifier was provided in the request.

Expected action

Clarify if the API provider may | should include the $.device property if only a single identifier was provided in the request.

Additional context

[eric-murray]

The API Design Guide itself is clear

A DeviceResponse object is defined for this purpose, but is not mandatory to be used by any API. Where it is used, the API provider MUST indicate in responses which device identifier has been selected when multiple device identifiers were provided, and MAY also include this information when only a single device identifier has been provided. In all cases, the API provider MUST NOT respond with an identifier that was not originally provided by the API consumer.

[Kevsy]

Great, thanks Eric - in that case the first paragraph of the schema description can align with that, e.g.:

"An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only will be returned when the API consumer includes the device parameter in their request (i.e. they are using a two-legged access token), and is relevant when and specifies more than one device identifier is specified, as only one of those device identifiers is allowed in the response.. Otherwise it may be returned when only a single device identifier has been provided."

[eric-murray]

The last sentence of your proposal introduces a new ambiguity, because the "otherwise" could be interpreted to mean "not using a two-legged access token".

I'm struggling to see a scenario where different API providers including or not including the device identifier in their response when only one was provided in the request can cause issues for the API consumer, because they know which and how many identifiers they provided.

But if you want to revise the wording, how about:

An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter can only be returned when the API consumer includes the device parameter in their request (i.e. they are using a two-legged access token). It is mandatory when more than one device identifier is provided, but optional if only a single device identifier is provided.

[Kevsy]

The last sentence of your proposal introduces a new ambiguity, because the "otherwise" could be interpreted to mean "not using a two-legged access token".

Good point 🤦‍♂️ I prefer your revised wording, thanks!

I'm struggling to see a scenario where different API providers including or not including the device identifier in their response when only one was provided in the request can cause issues for the API consumer, because they know which and how many identifiers they provided.

I agree, rather my reason for raising this was regarding test definitions. Here's an example from quality-on-demand-createSession.feature:

# Additionally, any success response has to comply with some constraints beyond the schema compliance
And the response property "$.device" exists only if provided in the request body and with the same value

That condition reads to me as:

• if it was provided in the request, include it in the response (i.e. it expects it will be included when a single identifier was passed in the request)
• the value must be the same (i.e. if multiple identifiers were provided, all must be returned, in contradiction of the schema)

So if we adopt your revised description text, and define a reworded condition that can be used across .features, then that would remove the ambiguity.

[eric-murray]

Ah, OK - two points here:

• Whilst Commonalities says including device in the response is optional when only a single device identifier was provided in the request, an API may chose to make it mandatory.
• The same value statement was strictly correct when multiple identifiers were provided, as conflicting identifiers would result in an error. But now, it requires some "interpretation", as the requirement that the device identifier in the response must be the "same value" as one provided in the request remains.

I'd propose two formulations, dependent on whether an API requires the device object is always returned (for 2-legged access tokens), or leaves that up to the API provider.

Up to API provider
And the response property "$.device" exists only if provided in the request body and always if more than one device identifier is provided, and contains a single device identifier that was included in the request

Mandatory for the API
And the response property "$.device" exists if it was provided in the request body, and contains a single device identifier that was included in the request

Where the test is anyway part of a 2-legged test, the if provided in the request body bit could be dropped, as that is anyway a requirement when 2-legged access tokens are used, so should be captured by a test on the request body itself.