Initial API proposal

[eric-murray]

What type of PR is this?

• initial API proposal

What this PR does / why we need it:

This is the initial proposal from Vodafone for the KYC Tenure API

Which issue(s) this PR fixes:

Fixes #12

Special notes for reviewers:

None

Changelog input

 release-note
 - Initial API proposal

Additional documentation

None

[GillesInnov35]

hi @eric-murray , thanks a lot for this good proposal, it's OK. I've a question on what we've started to discuss on discussions #7 and #8. What do you think about adding those rules in the API overview.

[eric-murray]

@GillesInnov35
Once the rules on generating the tenure response are agreed, then these can indeed be added to the API definition as documentation.

But there is no need to wait for these rules to be agreed before merging this PR. This is just a "work in progress" version, which will be subject to further updates before being released as an initial version. Further updates can be pushed to the repository as they are agreed.

[GillesInnov35]

Thanks
BR
Gilles

[eric-murray]

Thanks @GillesInnov35

I won't merge this until others have raised any questions they may have, and have given their approval as well. It should also be discussed during at least one of the bi-weekly KYC meetings. As the next meeting is tomorrow, I think we are looking at waiting until after the subsequent meeting before merging this.

And I also need approval for PR #13. Currently, the YAML linter does not like line lengths more than 80 characters. That PR is required so that that rule can be disabled.

[GillesInnov35]

OK Thanks a lot Eric

[eric-murray]

OK Thanks a lot Eric

Hi @GillesInnov35. I was re-adding @camaraproject/tenure_maintainers as a reviewer to bring this PR to the attention of Telefonica, who have no codeowner for this repository, but are maintainers. Now I have just added @claraserranosolsona and @jgarciahospital directly as reviewers, which is perhaps simpler. I would like Telefonica feedback on this proposal before merging.

[GillesInnov35]

Hi @eric-murray, tenureDateCheck is currently a boolean attribute. I wonder if the API will have also to return the information that the date comparison could not been done because the MNO do have the correct information, and then return "not_available".
What do you think about that ?

BR
Gilles

[eric-murray]

Hi @GillesInnov35

Can you clarify your proposal? Is this to handle mobile subscribers for which no answer can be given, because their tenureDate is just not known? Or is it to handle the situation that the requested tenureDate is so long ago that the MNO cannot verify that date, but could verify a later date?

The assumption behind the API design was that each mobile subscriber has a recorded tenure date with no limit on how long ago that was. So if a subscriber had the same MSISDN for, say, 20 years, then the tenure date would be known to be 20 years ago, and not "more than 10 years", for example.

Do we need to consider making the requested tenureDate relative? So rather than the API consumer asking about tenure since, for example, 14-10-2004, they would ask about tenure over the last 20 years. The advantage of using relative time periods is that a maximum can be easily specified in the OAS definition, and then all implementations would be expected to support this maximum.

Because date-time is a string format, a "minimum" or "maximum" date cannot be built in to the OAS definition itself, though of course the documentation could specify such a limit. But trapping dates that do not comply with such a requirement takes a bit more work.

[GillesInnov35]

Thanks Eric
Yes my wondering concerned the case when no answer can be given by the MNO. What will happen when the user is not the owner of the contract according to MNO and countries privacies ?
For the second point, I agree with you, using relative time period seems to to be more useful and simplier.
Perhaps to be reviewed in project meeting.

BR
Gilles

[GillesInnov35]

Other way, would be to return the date when the line was opened.
in this case operation would be POST /retrieve-tenure

[eric-murray]

What will happen when the user is not the owner of the contract according to MNO and countries privacies ?

Commonalities provide an error that can be used when a given service does not apply to a given "device" (in this case, subscription):

            GENERIC_422_DEVICE_NOT_APPLICABLE:
              description: Service is not available for the provided device
              value:
                status: 422
                code: DEVICE_NOT_APPLICABLE
                message: The service is not available for the provided device.

This was intended for cases such as querying the SIM Swap API with a fixed line phone number. I included this error in the proposed YAML.

Curiously, the SIM Swap API did not adopt this error, but instead defines:

            GENERIC_422_NOT_SUPPORTED:
              description: Not Supported
              value:
                status: 422
                code: NOT_SUPPORTED
                message: Service not supported for this phoneNumber

which is maybe because "device" can be viewed as a confusing term to use when it is identifying the subscription. But the mechanism is the same - there is an explicit 422 error defined for this case, rather than returning a 200 response which, on closer inspection, turns out to be an error.

[GillesInnov35]

Thanks Eric, OK it works and the response error seems to be clear. So "not-available" is not useful.

Gilles

[HuubAppelboom]

@eric-murray

Hi Eric,

It may be better to follow the SIm Swap 422 error message, because it is indeed for the phone number (and not the device)

[fernandopradocabrillo]

Hi @eric-murray! Thanks for crafting the initial PR.
Sorry for the late review, from TEF we are also interested in this API.

[eric-murray]

Hi @HuubAppelboom

The message is just an example, and API providers can always change it to something more relevant. Indeed, we could change the example in the OAS definition if we prefer a different message to that in the Commonalities common JSON file.

What does need to be standardised are the codes. Code NOT_SUPPORTED is not defined as a valid code by Commonalities, so that needs to be fixed. Either SIM Swap (or one of the other APIs that use this code) need to submit it to Commonalities, or they need to adopt an existing valid code.

Commonalities should tighten up code definitions for the next update of their design guidelines, so let's see what they define then.

[GillesInnov35]

Thanks Eric

[eric-murray]

@fernandopradocabrillo, @grgpapadopoulos
What is your view on the current proposal?

[fernandopradocabrillo]

Hi @eric-murray, thanks for adjusting the proposal. We are reviewing internally with our product team and we'll get back to you ASAP

[eric-murray]

@fernandopradocabrillo @GillesInnov35 @grgpapadopoulos
Any update on your acceptance or otherwise of this PR following the recent KYC meeting?

[GillesInnov35]

Thanks @eric-murray ,

[GillesInnov35]

Thanks

[fernandopradocabrillo]

Thanks for the updates. We have been checking internally and we can go ahead with this proposal.

LGTM