New Proposal - Capability and Runtime Restrictions

[gmuratk]

CAMARA Service APIs are designed with many optional parameters and features. It’s unreasonable to expect each API Producer (i.e. Operator) to support all these optional parameters. In addition, some supported features and parameters may not be enabled at Service API invocation time, based on network state, who might be invoking and/or for whom/which device, location, …) There is currently no mechanism to exchange such information with API Consumers (i.e. Application Service Providers (ASP)/Developers/Aggregators) and keep the CAMARA APIs the same across the Exposure Gateways.

This API proposes reuse of JSON schema to communicate 'limits' enforced by API Producer/Provider to developers.

[gmuratk]

PR camaraproject/WorkingGroups#384 created.
Also issue opened for discussion in Commonalities in camaraproject/Commonalities#126

[jordonezlucena]

I think this an issue eligible to Commonalities Sub-Project, no for WGs.
The link on issue 126 you pointed out does not work

[Kevsy]

@jordonezlucena I agree this is appropriate for a Commonalities discussion and not a new sub-project

[gmuratk]

I think this an issue eligible to Commonalities Sub-Project, no for WGs. The link on issue 126 you pointed out does not work

Updated with the correct link. Thank you,

Just to clarify, this is indeed a new API proposal. I'll leave it up to process to decide if it requires a new sub-project or become part of Commonalities. Regardless, as it has an overarching impact on all subprojects, it should be discussed in Commonalities, hence the issue opened up for in that subproject.

[bigludo7]

Hello @gmuratk
I understood the problem to be solved (be able to provide the feature & limitation of a given API implementation) but for me we should work to no have this problem.

If we have this problem "It’s unreasonable to expect each API Producer (i.e. Operator) to support all these optional parameters" that mean that we have probably miss the boat on CAMARA.

We cannot deliver partial implementation to developer and this is probably one of the key of success. If we do that it means that a developer making code for Telco A will have a failure calling Telco B. Her/His experience with CAMARA will be a feel as a fail.

We have to work on the granularity and the simplicity of the CAMARA APIs to avoid this problem.

And if we have the problem I got the feeling that online documentation should be good enough. I'm struggling to imagine that a developer will code an API client to get a given implementation capabilities & limitations.

[lbertz02]

@bigludo7,

When an operator is informed that they must accommodate an optional parameter, they often interpret this as an obligation to enable the corresponding feature within their network. However, accommodating should only extend to supporting requests containing the optional parameter associated with a feature that their network does not provide. (Note I used the term accommodate instead of the overloaded support term here).

Now, let’s delve into a scenario involving diligent network operators who have successfully transitioned to IPv6-only networks. Imagine their reaction upon encountering that “support” of the IPv4 addresses in Device Identification actually meant providing IPv4 addresses to their network. Their response is unequivocal: such a requirement is unreasonable!

I believe none of us are implying optional parameter support in a request mandates feature support in a network.

With respect to simplification and "code once" we are enabling developers to use a single interface and understand, in real time, what “optional” things are more or less meaningful/useful.

For example, if an operator’s network does not provide IPv6 addresses they can proactively communicate this. The developer can write code that doesn’t blindly grab the first address it encounters—avoiding the pitfall of all such requests resulting in “Device not found” errors.

While IPv6 only support represents a permanent state for that specific network, other scenarios are more transient. For instance:

1. Network Congestion: Temporary network congestion could lead to unsuccessful Quality of Data (QoD) requests. Why not inform the developer beforehand so they can disable the button a user might press to initiate such a request?

2. Geographic Restrictions: In certain geographic regions, the minimum allowed location accuracy might differ—for example, 3 km versus the 2 km minimum value in the interface. Developers can observe the numeric restriction being applied in real time and ensure compliance with the minimum value in their code.

By preemptively avoiding requests that result in negative user experiences (e.g., QoD unavailability) or outright errors (e.g., location values falling below the allowed minimum for the device’s geographic region, inadvertently revealing its approximate location), we reduce the number of unsuccessful interactions. This is all possible without changing the API and reflect many of the real world situations.

[bigludo7]

Thanks @lbertz02 for your answer.

I'm not fully agree on the UC (if I did not provide anymore IPv4 address then I will not get request with IpV4 probably) but OK got the rationales.

But I'm still doubtful about the point: Are you sure we need an API for that while documentation should be just good enough?
Implementing an API is an effort so not sure about the value to do that for the consumer/developer.

Sorry to be provocative, but we're working on a standard (and following this standard is a key factor for success) but here we're providing an API describing how we're not standard. As having a limitation should be an exception agreed?

[lbertz02]

The IPv4 is often cited but the more frequent and practical use cases are the transient ones imo.

3gpp Supported Features are conveyed at runtime. The apis should focus on what is possible and make things associated aspects optional in some form. unfortunately, tying the dynamic mechanism like 3gpp Supported Features to the api is a part of the objective of this proposal.

the challenge is tying a dynamic Supported Feature in a meaningful way to an api. this is another aspect of the proposal. Tying programmatically is a bit more straight forward for developers even if it feels complicated which we feel it is not but such things are a matter of opinion.

relying on documentation is important but I may be a bit provocative in saying that relying solely on documentation may be too much.

finally, regional differences and regulations are not something we should burden api design teams with. I don't understand some of them but work under the assumption they exist for a reason.

[TEF-RicardoSerr]

Hello @gmuratk
Could you please provide me with the list of initial Maintainers for the new subproject?

[gmuratk]

@TEF-RicardoSerr you can put: @gmuratk and @lbertz02 in the initial Maintainers. Thx

[gmuratk]

@jgarciahospital as time ran out in the API Backlog call yesterday (Sept 26, 2024), I couldn't provide an update. Given the alternate timing of the meetings, I'll not be able to join until the following meeting. Please find the couple slides providing an update embedded in the API Backlog Minutes: Capabilities_and_Runtime_Restrictions_Update.pptx

We request this proposal to be taken to TSC for request of 'sandbox' creation?

[jgarciahospital]

Hi Murat,

As proposal was already considered and approved in backlog to be proposed to TSC, I don't see any problem on pushing it this thursday. Please confirm your presence on the next TSC (3rd October, 10-11:30 CET/UTC+2)

[gmuratk]

Hi Murat,

As proposal was already considered and approved in backlog to be proposed to TSC, I don't see any problem on pushing it this thursday. Please confirm your presence on the next TSC (3rd October, 10-11:30 CET/UTC+2)

Thank you, Jorge. Unfortunately, I can't commit to this week's TSC, but I can be there at the next TSC, I believe on October 17th).

[jgarciahospital]

Perfect! I take note of it.

[jgarciahospital]

Hi @gmuratk, can you upload in the PR #74 the documentation included in those minutes? The folder https://github.com/camaraproject/APIBacklog/tree/main/documentation/SupportingDocuments is a good place for it.