Consolidate api information into yaml file #52

fernandopradocabrillo · 2023-09-06T13:09:06Z

What type of PR is this?

Add one of the following kinds:

cleanup
documentation

What this PR does / why we need it:

Include API documentation into yaml file and remove extra md files
Rename api spec file to "sim_swap.yaml" since previous name "checkSimSwap.camara.swagger.yaml" no longer reflects the actual status of the API:
- check is no longer the only operation available in the spec
- there is no need to keep the distinction of camara since we no longer have MC version
- since we are developing in openapi I think we don't need to include the swagger reference

Which issue(s) this PR fixes:

Fixes (#42)

Special notes for reviewers:

Issue #42 still has an open issue regarding the authorization flows to be implemented in the API, as we were waiting for a resolution in the discussions on Identity and Consent. This decission could lead to changes in the requests properties (Link to Mona's comment) so, if you are okey with it @bigludo7, @DT-DawidWroblewski, I suggest moving that topic to a new Issue and close #42 with the embeded documentation and the complete cleanup.

Changelog input

N/A

Additional documentation

N/A

DT-DawidWroblewski · 2023-09-06T13:36:21Z

code/API_definitions/sim_swap.yaml


-    [GSMA Mobile Connect Account Takeover Protection specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.24-Mobile-Connect-Account-Takeover-Protection-Definition-and-Technical-Requirements-v2.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/).


@fernandopradocabrillo I think we agreed to leave this reference in documentation... please change accordingly and do not delete this piece.

yes @DT-DawidWroblewski It is still there, I moved it to the section Further info and support.

DT-DawidWroblewski · 2023-09-06T13:38:10Z

code/API_definitions/sim_swap.yaml

@@ -35,13 +59,14 @@ paths:
  /retrieve-date:
    post:
      security:
-        - oAuth2ClientCredentials: []


what about countries where oauth2ClientCredentials is allowed? we should keep this.

The idea that is being discuss in the commonalities Issue (camaraproject/Commonalities#53) is to encapsulate the Authorization flows into the .well-known file of the OIDC protocol. ~~This does not mean that we removed the client_credentials grant type, it is just not explicitly described inside the securitySchemes~~

Edited

I'd keep it to avoid confusion while reading the yaml file

@DT-DawidWroblewski may I suggest you also raise your concern in the camaraproject/Commonalities#53 ? i think it is important to provide your feedback at this level as it will impact all API.
@fernandopradocabrillo probably better to wait Commonalities outcome on this PR before to apply no ?

@bigludo7 yes I also think we can wait until the commonalities PR is merged. I was just advancing some work!

@DT-DawidWroblewski I retract this as I was not aware that it has been agreed in the discussions on Identity and Consent that resources that manage personal data cannot be accessed using client_credentials.

Source: https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md

and:

camaraproject/IdentityAndConsentManagement#57

Any reference to other securitySchemes, such as client credentials, would generally be removed. Client credentials access (2-legged) must only be used "when user resource is NOT involved & the client belongs to confidential category".

DT-DawidWroblewski · 2023-09-06T13:38:34Z

code/API_definitions/sim_swap.yaml

@@ -76,13 +104,14 @@ paths:
  /check:
    post:
      security:
-        - oAuth2ClientCredentials: []


what about countries where oauth2ClientCredentials is allowed? we should keep this.

DT-DawidWroblewski · 2023-09-06T13:39:13Z

code/API_definitions/sim_swap.yaml

@@ -116,21 +148,9 @@ paths:
          $ref: "#/components/responses/Generic504"
 components:
  securitySchemes:
-    oAuth2ClientCredentials:


we cannot delete this option as oauth2clientCredentials is an option that is available on many markets

bigludo7

Thanks for that.
One question about the version - as you change code for scope & header should be still v4.1 or v4.2 or v5.0-wip?

hdamker · 2023-09-07T09:11:13Z

@fernandopradocabrillo

I strongly propose to have two different PRs:

One to consolidate the documentation into the YAML file. It's documentation only and will not impact the upcoming version number of a release (or just the patch number)
Changes of the YAML file, e.g. discussion about security schema

Doing it in one PR will make it complex and will block the independent changes.

fernandopradocabrillo · 2023-09-07T11:51:35Z

@fernandopradocabrillo

I strongly propose to have two different PRs:

One to consolidate the documentation into the YAML file. It's documentation only and will not impact the upcoming version number of a release (or just the patch number)

Changes of the YAML file, e.g. discussion about security schema

Doing it in one PR will make it complex and will block the independent changes.

@hdamker @bigludo7 @DT-DawidWroblewski Updated this PR to only include the documentation in the yaml. I'll create a new one with then changes in the scopes, headers, etc

bigludo7

Look good for me.
I'm fine for this one to keep same version as we just added documentation but probably in future update we should change the last didit version no?

DT-DawidWroblewski · 2023-09-07T13:44:34Z

it is ok. thanks @fernandopradocabrillo

fernandopradocabrillo · 2023-09-07T14:05:34Z

Look good for me. I'm fine for this one to keep same version as we just added documentation but probably in future update we should change the last didit version no?

Yes, I have updated to v0.5.0-wip in the PR with the yaml changes. I don't know exactly what convention are we following in the versioning so I'm open to suggestions!

fernandopradocabrillo added the documentation Improvements or additions to documentation label Sep 6, 2023

fernandopradocabrillo requested a review from DT-DawidWroblewski as a code owner September 6, 2023 13:09

fernandopradocabrillo self-assigned this Sep 6, 2023

fernandopradocabrillo requested a review from bigludo7 as a code owner September 6, 2023 13:09

DT-DawidWroblewski reviewed Sep 6, 2023

View reviewed changes

bigludo7 reviewed Sep 6, 2023

View reviewed changes

move api documentation to yaml

a9fe4c2

fernandopradocabrillo force-pushed the include-api-documentation-into-yaml-file branch from c9fed64 to a9fe4c2 Compare September 7, 2023 11:47

fernandopradocabrillo requested a review from bigludo7 September 7, 2023 11:51

fernandopradocabrillo changed the title ~~Consolidate api information into yaml file and sync with commonalities~~ Consolidate api information into yaml file Sep 7, 2023

fernandopradocabrillo mentioned this pull request Sep 7, 2023

Include OIDC securityScheme, format scopes and add x-correlator header #53

Merged

bigludo7 approved these changes Sep 7, 2023

View reviewed changes

DT-DawidWroblewski merged commit 1f65514 into camaraproject:main Sep 7, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consolidate api information into yaml file #52

Consolidate api information into yaml file #52

fernandopradocabrillo commented Sep 6, 2023 •

edited

Loading

DT-DawidWroblewski Sep 6, 2023

fernandopradocabrillo Sep 6, 2023

DT-DawidWroblewski Sep 6, 2023

fernandopradocabrillo Sep 6, 2023 •

edited

Loading

DT-DawidWroblewski Sep 6, 2023

bigludo7 Sep 6, 2023

fernandopradocabrillo Sep 6, 2023 •

edited

Loading

fernandopradocabrillo Sep 6, 2023

DT-DawidWroblewski Sep 6, 2023

fernandopradocabrillo Sep 6, 2023

DT-DawidWroblewski Sep 6, 2023

DT-DawidWroblewski Sep 6, 2023

fernandopradocabrillo Sep 6, 2023

DT-DawidWroblewski Sep 6, 2023

bigludo7 left a comment

hdamker commented Sep 7, 2023

fernandopradocabrillo commented Sep 7, 2023

bigludo7 left a comment

DT-DawidWroblewski commented Sep 7, 2023

fernandopradocabrillo commented Sep 7, 2023


		[GSMA Mobile Connect Account Takeover Protection specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.24-Mobile-Connect-Account-Takeover-Protection-Definition-and-Technical-Requirements-v2.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/).

Consolidate api information into yaml file #52

Consolidate api information into yaml file #52

Conversation

fernandopradocabrillo commented Sep 6, 2023 • edited Loading

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Changelog input

Additional documentation

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fernandopradocabrillo Sep 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fernandopradocabrillo Sep 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bigludo7 left a comment

Choose a reason for hiding this comment

hdamker commented Sep 7, 2023

fernandopradocabrillo commented Sep 7, 2023

bigludo7 left a comment

Choose a reason for hiding this comment

DT-DawidWroblewski commented Sep 7, 2023

fernandopradocabrillo commented Sep 7, 2023

fernandopradocabrillo commented Sep 6, 2023 •

edited

Loading

fernandopradocabrillo Sep 6, 2023 •

edited

Loading

fernandopradocabrillo Sep 6, 2023 •

edited

Loading