Brand Registration API Proposal

[alpaycetin74]

An API proposal for the registration phase of the Verified Caller API

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

• to start API spec discussions for the registration phase

Which issue(s) this PR fixes:

Fixes #24

Special notes for reviewers:

Changelog input

release-note

Additional documentation

[github-actions]

🦙 MegaLinter status: ✅ SUCCESS

Descriptor	Linter	Files	Fixed	Errors	Elapsed time
✅ ACTION	actionlint	2		0	0.03s
✅ OPENAPI	spectral	1		0	1.82s
✅ REPOSITORY	git_diff	yes		no	0.01s
✅ REPOSITORY	secretlint	yes		no	0.67s
✅ YAML	yamllint	1		0	0.44s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

[GillesInnov35]

thanks @alpaycetin74 ,very interesting with full operations to manage registration REST entity record.

But I've just one first comment. From what I've designed in CAMARA API projects, CAMARA and GSMA prefer verb instead of entity (registration in our case). I know that OAS3 recommend such syntax.
Perhap I'm wrong and some APIs already use entity management such as you propose.
Let me check CAMARA Commonalities 5.0.

[GillesInnov35]

@alpaycetin74, according to commonalities examples, my comment was wrong. sorry.
Let's start the dicussion with your proposal.
Thanks

[GillesInnov35]

Could we replace campaign by campaignName.
Following REST rules, response to a POST /entity (creation) shoudl return the description of the full entity description yet created: in fact all parameters + registrationId.
WDYT

[alpaycetin74]

Could we replace campaign by campaignName. Following REST rules, response to a POST /entity (creation) shoudl return the description of the full entity description yet created: in fact all parameters + registrationId. WDYT
Yes, both ideas seem reasonable to me.
Maybe "campaignId" is better, similar to "clientId"

[GillesInnov35]

@alpaycetin74, in my opinion campaign is not a resource in our case only a strong name/description unlike to a client resource which must exist in the information system. That's why I proposed a name and not a id.
Regarding your very interesting proposal for registration resource management, I'll discuss with my colleagues internally before next meeting on Thursday 22th.
Thanks
Gilles

[DENGYONG18]

Hello @GillesInnov35, I didn't receive a notice of the meeting, can you post me a link to the meeting?

[GillesInnov35]

hello @DENGYONG18 , there's no notification. You can refer to the LFX Meeting agenda
https://zoom-lfx.platform.linuxfoundation.org/meetings/telcoapi?view=week

[DENGYONG18]

Thanks @GillesInnov35 ！I'm sorry for missing the discussion at previous meeting, and I have read your minutes in Issue #24 and got a rough idea of what was discussed. I'll join you all in tomorrow meeting.

[GillesInnov35]

@alpaycetin74, may I ask you some questions regarding your yaml proposal to clearly understand what you mean.
I see that partnerId has been added in the request header (except POST). 2-Legged access token provide an applicationId which will be associated with a partner o MNO side, won't it ?
A device has replaced the phoneNumber to cover mobile phone but also others device (ipv4, ipv6). Do you have some Use cases in which such devices could be involved for Branded Calling API ?
Thanks a lot
Gilles

[alpaycetin74]

Hello @GillesInnov35 ,
In VF parlance, a partner, sometimes called an integrator, is an actor that sells the branded calling service to companies, e.g. banks. The API can be called directly by the end user (bank) or by the partner/integrator on behalf of the end user.
We decided it was superfluous to include the partner id in the API request. So I should have removed the partnerId from the other operations as well. I'll do that soon, and in the meantime can you ignore this parameter please.

The device parameter is typical in CAMARA to uniquely identify a device by one of the four parameters, or combinations of them

The purpose of the parameter is to provide a flexible means of identifying a device.
In most cases, CAMARA APIs simply use phoneNumber (MSISDN), but for instance in Quality on Demand API, the device's current IP address matters and it must be provided.
In our case, I think it is unlikely to benefit from the other identifier types. For now we just wanted to stick to using the "device" parameter as usual, but it could be dropped.
And we also added the "phoneNumberAlternate" parameter under "device" because in certain cases, e.g. if the device is behind a PBX, a pair of phone numbers may be needed to identify it uniquely. In SIP protocol, those correspond to From and PAI headers.

Hope this helps.

[alpaycetin74]

We also checked with Eric Murray and he thinks we can simply use phoneNumber and phoneNumberAlternate parameters in the request body. No need to reuse the device parameter. That's simpler for us. I will update the spec as such. @GillesInnov35

[alpaycetin74]

I have updated the spec with the discussed changes.

• POST and PUT return the full registration record.
• Removed the superfluous partnerId header
• Replaced the device parameter with phoneNumber & phoneNumberAlternate pair.

I am also happy to rename the campaign parameter to campaignName, just wanted to ask beforehand if a single registration could be associated with multiple campaigns at the same time? In that case we could make it an array of strings.
Happy to receive any other comments. Thank you.

[GillesInnov35]

hello, we have a request from our legal entity recommending that reseller/aggregator should never know b-number regarding GDPR. As the caller doesn't know which is the operator for b-number to directly call it, it would mean b-number should be hashed.
It seems to be much complex. Do you have such a recommendation ?

[DENGYONG18]

Hello @GillesInnov35 , “Reseller/aggregator should never know b-number regarding GDPR” refers to the brand registration process or the pre-authorization process?

[GillesInnov35]

hello @DENGYONG18 , it concerns pre-announce

[alpaycetin74]

hello, we have a request from our legal entity recommending that reseller/aggregator should never know b-number regarding GDPR. As the caller doesn't know which is the operator for b-number to directly call it, it would mean b-number should be hashed. It seems to be much complex. Do you have such a recommendation ?

This looks too complicated. It requires a key exchange between the API client and the service provider (not the integrator in between) so that API client can encrypt the B-number and service provider can decrypt it.
And the integrator cannot see this exchange because otherwise they could decrypt the B number.
I don't know how this could be done in practice.

[GillesInnov35]

thanks @alpaycetin74 . This string recommendation from our legal entity won't have any impact on the API specifications /pre-announce. But it may push reseller to expose a Telco-finder API to allow API consumer to find b-number's operator.

[GillesInnov35]

LGTM thanks

[olsi-korkuti]

hello, we have a request from our legal entity recommending that reseller/aggregator should never know b-number regarding GDPR. As the caller doesn't know which is the operator for b-number to directly call it, it would mean b-number should be hashed. It seems to be much complex. Do you have such a recommendation ?

This is a good point, but practically speaking, is not the MNOs that expose the B-number to the reseller. Usually the Company consumes an API to the reseller (where can provide the B-number) and then the reseller would use that information to find the telco owner. In theory if the Company does not want to share B-number data, they can consume the API to the Telco platform directly assuming they also have access to a Telco Finder API.
A safe approach could be to consume Telco Finder API either from another aggregator or the Telcos and Pre-Announce the call directly to the Telco Platform.

[DENGYONG18]

Hello @alpaycetin74 ,I think this YAML file is pretty good overall. But the file should be rename like "Verified Caller- Registration" at this phase, right? Additionally, I realized that the Introduction Part was incomplete, could you complete it at your convenience? :)

[alpaycetin74]

Hello @alpaycetin74 ,I think this YAML file is pretty good overall. But the file should be rename like "Verified Caller- Registration" at this phase, right? Additionally, I realized that the Introduction Part was incomplete, could you complete it at your convenience? :)

Hello, I will complete the missing parts. Since we are in the release candidate phase, these are not urgent at the moment. Thank you.

[alpaycetin74]

Hello @stroncoso-quobis , could you review this PR so that we can proceed to the release candidate preparation ? Thank you.

[stroncoso-quobis]

LGTM!

Nice work, now approved, I will add this reference to the UML in progress at #34
Best regards,