Separate endpoints into different APIs

[NoelWirzius]

In this issue the topic of separating the different endpoints into separate APIs should be covered.
The split makes sense to be aligned with the other Camara Subprojects like "Device Location". On the other hand this will also helps the productization of the APIs and a clear offering from the telco industries.

Suggestion:

• 1 API for Roaming + Roaming subscription
• 1 API for Connectivity + Connectivity subscription

[jgarciahospital]

Thanks Noel for opening back this discussion. We totally support this approach based on this rationale:

• CAMARA is pushing for atomic and use case driven APIs
  → Current scope of this API is fulfilling separate use cases and more complex functionality than an atomic feature

• Validation of APIs, based on ATPs and certification process, requires full support of all the features of each API
  → Forcing operators/developers to implement additional use cases only because of a version evolution or, worst situation, partial deployments

• Atomic endpoint evolution is currently tied to the full API evolution
  → New features of specific use cases / endpoints cannot be included until the complete API is agreed, delaying use case evolution even for bug fixing

Based on this, Telefonica proposes to follow the same strategy as other APIs (like location, SIM Swap...), separating features and use cases in separated atomic APIs:

1. Device Status (roaming)
2. Device Status (connectivity)
3. Device Status (roaming) subscription
4. Device Status (connectivity) subscription

[JoachimDahlgren]

This is opening up the discussion from last summer ##55. Is there anything that has changed since then? At that time there was a summary written in #https://github.com/camaraproject/DeviceStatus/blob/main/documentation/SupportingDocuments/decision-support-1-or-2-apis.md

[bigludo7]

Hello
Totally support also from my side as well to have 4 APIs like suggested by @jgarciahospital.

@JoachimDahlgren - since we discussed months ago we coded/implemented this APIs and this effort changed our perspective on this. We shared the rationales listed by Jorge.

I believe that the "All or Nothing" approach for an API implementation is a key to adoption and partial implementation is not manageable for our consumer.

[NoelWirzius]

@bigludo7 @jgarciahospital from dt side we also supporting the approach with 4 APIs and will commit to this.

We need to check if it makes sense to have the API-Name in the event or coming here more from the functional side.

[sachinvodafone]

I believe this is a common issue across all APIs, with each API handling these issues differently. To address this, I've initiated a discussion focusing on commonalities to establish a design pattern for addressing these issues, which can then be referenced by other APIs.

[bigludo7]

Any update on this one?

I saw support from DT (@NoelWirzius ), Telefonica (@jgarciahospital ) & Orange.
@sachinvodafone and @JoachimDahlgren as steady attendees to this WG do you have any blocking points to split the API?

As we have preparing the September release better to tackle this point soon.
Thanks

[akoshunyadi]

We could do the split after v0.6.0.

But we should first agree on the API names, do we want to have them so long, like this?

• device-status-roaming.yaml
• device-status-connectivity.yaml
• device-status-roaming-subscriptions.yaml
• device-status-connectivity-subscriptions.yaml

[sachinvodafone]

I support the idea of having four separate YAML files to address separation of concerns. However, without clear API design rules for our Camara project, different teams might opt for different approaches (such as separate endpoints versus separate YAML files)when dealing with the same design problem.

[bigludo7]

@akoshunyadi looking of what we add for Device Location project (here) we can probably remove device-status in the name.
What about

• roaming.yaml
• connectivity.yaml
• roaming-subscriptions.yaml
• connectivity-subscriptions.yaml

The interesting point raised by @shilpa-padgaonkar here make me like simple api name :)

[jgarciahospital]

LGTM

[shilpa-padgaonkar]

@akoshunyadi @bigludo7 @jgarciahospital @NoelWirzius

I am bit concerned that the names connectivity and connectivity-insights (API in https://github.com/camaraproject/ConnectivityInsights/ ) seem almost similar.

How do we differentiate the 2?

[jgarciahospital]

Reachability sounds good:

• roaming.yaml
• reachability.yaml
• roaming-subscriptions.yaml
• reachability-subscriptions.yaml

[akoshunyadi]

We could introduce product categories in Camara, like device, home, network, etc...
So the api name would be prefixed like <product category>-<feature>.yaml:
device-roaming.yaml
device-connectivity.yaml
device-roaming-subscriptions.yaml
device-connectivity-subscriptions.yaml

the same for location

so we only have to have a unique feature name within the category

[bigludo7]

Good point @shilpa-padgaonkar
I'm fine with @jgarciahospital proposal for reachability

@akoshunyadi as it will impact other API isn't a topic for commonalities?
I tend to prefer simplicity but get your point.
Perhaps we can explore other means to categorize the API? in meta release description for example or on a CAMARA page...

[akoshunyadi]

I think we should use now the chance with the new names to enhance the structure/organization of our APIs.
Sure, I'll create an issue in Commonalities.

[akoshunyadi]

camaraproject/Commonalities#178

[fernandopradocabrillo]

From TEF we are hoping to be able to bring this change into v0.6.0 since we all already agreed to apply it.
In the last meeting minutes I can see that it is marked for v0.6.0 alpha2, but I'm not quite sure which moment is that.
can you clarify @akoshunyadi ?

[akoshunyadi]

@fernandopradocabrillo yes, the splitting issue will be a part of 0.6.0. With the alpha1 we'd just like to bring some more quality into 0.6.0, so that we receive some developer feedback to all those other changes.

[maxl2287]

@akoshunyadi shell the version be:

• version: 0.6.0-alpha.2
• url: "{apiRoot}/<...>/v0.6alpha2"

?

[bigludo7]

Following discussion with @fernandopradocabrillo on the PR #152, here a proposal for the API naming:

API to retrieve 'on the fly' reachability status. Name: reachability-status endpoint: /retrieve
API to retrieve 'on the fly ' roaming status. Name: roaming-status endpoint: /retrieve
API to subscribe to reachability notification. Name: reachability-status-subscriptions (the endpoint is /subscriptions)
API to subscribe to roaming notification. Name: roaming-status-subscriptions

Looking for team feedback to close this work.

[akoshunyadi]

@akoshunyadi shell the version be:

* `version: 0.6.0-alpha.2`

* `url: "{apiRoot}/<...>/v0.6alpha2"`

?

@maxl2287 it should be wip for now, and the release-preparation PR will set the correct ones

[akoshunyadi]

Following discussion with @fernandopradocabrillo on the PR #152, here a proposal for the API naming:

API to retrieve 'on the fly' reachability status. Name: reachability-status endpoint: /retrieve API to retrieve 'on the fly ' roaming status. Name: roaming-status endpoint: /retrieve API to subscribe to reachability notification. Name: reachability-status-subscriptions (the endpoint is /subscriptions) API to subscribe to roaming notification. Name: roaming-status-subscriptions

Looking for team feedback to close this work.

Fine for me, but now all 4 APIs proposed start with "device- ". We can take those one too, with device as a context. Or are they too long?

[bigludo7]

@akoshunyadi I removed device to be aligned with device location.
For me it depends also the name of the subprojet. If we keep Device Status as the API family name we can avoid the word device in the api-name.

On this topic we probably need to review @hdamker proposal here
camaraproject/Governance#142 as I guess we need one lead repository for Device Status (without API directly described in it) and 4 child repo for our 4 APIs.... but this is not exactly what Herbert is describing.