SimSwap OAS with 2 endpoints (check & get date)

[bigludo7]

Hello,
Following Dec13th meeting, please see a proposal for a specific OAS definition pour simswap with 2 resources: retrieveSimSwapDate & checkSimSwap.
Thanks

[jlurien]

Comments are mainly cosmetic and to align API look & feel with the recently approved guidelines. For your consideration:

• max_age may be optional as we are defining a defaut value. I don't have a strong opinion here. Optional may be easier to use for consumers but defining it as required make consumers more aware of the threshold.
• For security we are assuming both client credentials and three_legged. I think this covers uncertainty about privacy or consents implications. However, as scopes are per operation we have to place security under each operation

[jlurien]

Securitization is being discussed transversely, but we are usually considering client credentials or three_legged in other APIs.

[monamok]

I leave some comments as improvements. I also suggest to remove "Create" word from the descriptions as there's anything being created here. I understand that it's because they're POST operations so I leave it to you to decide.

[bigludo7]

Thanks a lot @jlurien & @monamok for your valuable review.

Only one item pending: @jlurien you suggest I remove
`security:

• oAuth2ClientCredentials: []
• BasicAuth: []
• apiKey: []
• three_legged:
  • checkSimSwap
  • getSimSwapDate`

line 25-31 correct?

Just to be sure I got it correctly.

[jlurien]

Thanks a lot @jlurien & @monamok for your valuable review.

Only one item pending: @jlurien you suggest I remove `security:

• oAuth2ClientCredentials: []

• BasicAuth: []

• apiKey: []

• three_legged:

  • checkSimSwap
  • getSimSwapDate`

line 25-31 correct?

Just to be sure I got it correctly.

Yes, this global security is overriden by the security at operation level, so as we are defining a security per operation this global one takes no effect.

[monamok]

I just realized that "status" is missing in the errors. You might want to include it as well.
https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-design-guidelines.md#6-error-responses

[jlurien]

I just realized that "status" is missing in the errors. You might want to include it as well. https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-design-guidelines.md#6-error-responses

Yes, that is indeed in the guidelines. I didn't comment on that on purpose as we are not currently adding it in other v0.x APIs, but it could be added as we will have to eventually add it. We can do it now or in a feature version @bigludo7

[bigludo7]

Remove security schemes
add status for error

[bigludo7]

@monamok @jlurien @bigludo7 @DT-DawidWroblewski I updated the OAS following your review. I let you take a final look. Thanks.

[jlurien]

Just 2 minor suggestions and a couple of comments to keep in mind for future versions. Thank you so much for moving this forward and be so collaborative

[jlurien]

For a v1.x I think we should define an enum with specific error codes for the identified logical errors, e.g SIM_SWAP.MSISDN_REQUIRED, etc, but as we have pressure to close this, we can leave it now as a generic string, as it is in other v0.x versions

[bigludo7]

OK. Probably worth to be discussed in Commonalities.
We can probably raise a issue in commonalities to not forget this.

[jlurien]

Not sure if status will be required in v1.x as well, but as it is not present in other v0.x APIs, let's leave it as optional for now.

[bigludo7]

Same thinking on my side. I've checked QoD API for example and status is not there so my proposal is to have this attribute but optional for this release. Could be a topic for commonalities.

[bigludo7]

@DT-DawidWroblewski up to you for final review and merging if ok !
I will them complete documentation.

[bigludo7]

Hi @DT-DawidWroblewski
Any chance to have your approval today?
I would like to provide document & close this today by EOD
thanks

[monamok]

Just a small typo to fix and the rest looks good

[bigludo7]

Hi @DT-DawidWroblewski
Friendly reminder for review and then merging.
Thanks

[jlurien]

@DT-DawidWroblewski Please comment on this PR or merge it otherwise, so we can have both approaches in main