diff --git a/CHANGELOG.md b/CHANGELOG.md index 14e9e60..3aa9479 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,15 +3,68 @@ ## Table of contents +- **[r1.2](#r12)** - **[r1.1](#r11)** -- [v0.3.1](#v031) +- **[v0.3.1](#v031)** **Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.** +# r1.2 + +## Release Notes + +This release contains the definition and documentation of +* number-verification 1.0.0 + +The API definition(s) are based on +* Commonalities v0.4.0 +* Identity and Consent Management v0.2.0 + +## number-verification 1.0.0 + +**number-verification 1.0.0 is the release of the first stable version of the NumberVerification API.** + +- API definition **with inline documentation**: + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.2/code/API_definitions/number-verification.yaml) + +**Main Changes** + +* API and test definitions updated to conform to the Commonalities v0.4.0 and Identity and Consent Management v0.2.0 guidelines included in the CAMARA Fall24 meta-release +* Additional documentation & test cases added. +* Changed name of the file itself from number_verification.yaml to number-verification.yaml + + +### Added + +* User Story in documentation/API_documentation directory by @bigludo7 [PR118](https://github.com/camaraproject/NumberVerification/pull/118) +* Test Definition in Test_Definitions directory by @AxelNennker [PR124](https://github.com/camaraproject/NumberVerification/pull/124) + +### Changed + +* Aligned with CAMARA design guidelines & Identity Consent management by @AxelNennker +* Make the '+' mandatory for the phone number by @fernandopradocabrillo [PR90](https://github.com/camaraproject/NumberVerification/pull/90) +* Cosmetic change following megalinter integration by @bigludo7 [PR103](https://github.com/camaraproject/NumberVerification/pull/103) +* Update Authorization and authentication part accordingly to ICM by @fernandopradocabrillo [PR88](https://github.com/camaraproject/NumberVerification/issues/88) +* Adding a pattern for PhoneNumber in /verify by @maxl2287 [PR68](https://github.com/camaraproject/NumberVerification/issues/76) +* Clarify use of 'user' and 'subscriber' wording by @AxelNennker [PR102](https://github.com/camaraproject/NumberVerification/pull/102) +* Clarify that the sequence diagram in the yaml documentation is an example by @bigludo7 [PR139](https://github.com/camaraproject/NumberVerification/pull/139) + +### Fixed + +* Replaced OAuth2 auth code flow by OIDC auth code flow by @AxelNennker [PR109](https://github.com/camaraproject/NumberVerification/pull/109) + +### Removed + +* Removed documentation (replaced by doc in the yaml) by @AxelNennker [PR137](https://github.com/camaraproject/NumberVerification/pull/1379) + +## New Contributors +* N/A -# r1.1 - rc +# r1.1 ## Release Notes diff --git a/README.md b/README.md index bc5754e..08684e5 100644 --- a/README.md +++ b/README.md @@ -27,19 +27,15 @@ Repository to describe, develop, document and test the NumberVerification API fa ## Status and released versions * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**. -* **The latest pre-release of CAMARA Number Verification API is 1.0.0-rc.1 This is the release candidate of the first stable version of the API**. It is suitable for implementors. -* The Release Tag is [r1.1](https://github.com/camaraproject/NumberVerification/releases/tag/r1.1). - - API definition **with inline documentation**: - - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.1/code/API_definitions/number_verification.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.1/code/API_definitions/number_verification.yaml&nocors) - - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.1/code/API_definitions/number_verification.yaml) - -* The previous version 0.3.1 is available within the [release-0.3.1 branch](https://github.com/camaraproject/NumberVerification/tree/release-0.3.1): +* `NEW`: Release r1.2 with version 1.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r1.2) - API definition **with inline documentation**: - - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml&nocors) - - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/release-0.3.1/code/API_definitions/CAMARA/number_verification.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r1.2/code/API_definitions/number-verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r1.2/code/API_definitions/number-verification.yaml) + +* Previous releases and pre-releases of the repository are available in https://github.com/camaraproject/NumberVerification/releases +* For changes see [CHANGELOG.md](https://github.com/camaraproject/NumberVerification/blob/main/CHANGELOG.md) ## Contributorship and mailing list @@ -50,4 +46,4 @@ Repository to describe, develop, document and test the NumberVerification API fa ## Relevant Information -Since April 4th 2024 WG meeting minutes are placed in [Number Verification Wiki Confluence site](https://wiki.camaraproject.org/display/CAM/Number+Verification) +Since April 4th 2024 WG meeting minutes are placed in [Number Verification Wiki Confluence site](https://wiki.camaraproject.org/display/CAM/NumberVerification) diff --git a/code/API_definitions/number_verification.yaml b/code/API_definitions/number-verification.yaml similarity index 97% rename from code/API_definitions/number_verification.yaml rename to code/API_definitions/number-verification.yaml index 60f8a86..886ae34 100644 --- a/code/API_definitions/number_verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -30,6 +30,8 @@ info: # Sequence Diagram Number Verification API uses the **standard [OIDC Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call. + Note that the diagram shows just an example of a direct integration from developer's application and MNO's authserver and API, other scenarios of indirect integration via Aggregator/Channel Partner should also be considered. Specific authorization flows may apply, as defined by e.g. GSMA Open Gateway (OGW). + ![UML Sequence Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg) **Additional details:** @@ -50,13 +52,13 @@ info: # Further info and support [GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/). - version: wip + version: 1.0.0 x-camara-commonalities: 0.4.0 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - - url: '{apiRoot}/number-verification/v1rc1' + - url: '{apiRoot}/number-verification/v1' variables: apiRoot: default: http://localhost:9091 @@ -79,7 +81,7 @@ paths: operationId: phoneNumberVerify parameters: - in: header - name: X-Correlator + name: x-correlator required: false description: Correlation id for the different services schema: @@ -94,7 +96,7 @@ paths: '200': description: OK headers: - X-Correlator: + x-correlator: description: Correlation id for the different services schema: type: string @@ -129,7 +131,7 @@ paths: operationId: phoneNumberShare parameters: - in: header - name: X-Correlator + name: x-correlator required: false description: Correlation id for the different services schema: @@ -138,7 +140,7 @@ paths: '200': description: OK headers: - X-Correlator: + x-correlator: description: Correlation id for the different services schema: type: string diff --git a/code/Test_Definitions/NumberVerification_device_phone_number_share.feature b/code/Test_Definitions/number-verification-device-phone-number-share.feature similarity index 97% rename from code/Test_Definitions/NumberVerification_device_phone_number_share.feature rename to code/Test_Definitions/number-verification-device-phone-number-share.feature index 4d81091..c8b3e0d 100644 --- a/code/Test_Definitions/NumberVerification_device_phone_number_share.feature +++ b/code/Test_Definitions/number-verification-device-phone-number-share.feature @@ -1,11 +1,9 @@ - - @NumberVerification_device_phone_number_share Feature: Camara Number Verification API device phone number share # Input to be provided by the implementation to the tests # References to OAS spec schemas refer to schemas specified in -# https://raw.githubusercontent.com/camaraproject/NumberVerification/main/code/API_definitions/number_verification.yaml +# /code/API_definitions/number-verification.yaml # # Implementation indications: # * api_root: API root of the server URL @@ -15,7 +13,7 @@ Feature: Camara Number Verification API device phone number share # * a mobile device with SIM card with NUMBERVERIFY_SHARE_PHONENUMBER2 Background: Common Number Verification phone number share setup - Given the resource "/device-phone-number/v0" as base url + Given the resource "/device-phone-number/v1" as base url And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" is set to a UUID value diff --git a/code/Test_Definitions/NumberVerification_verify.feature b/code/Test_Definitions/number-verification-verify.feature similarity index 97% rename from code/Test_Definitions/NumberVerification_verify.feature rename to code/Test_Definitions/number-verification-verify.feature index 542cdfb..22d6362 100644 --- a/code/Test_Definitions/NumberVerification_verify.feature +++ b/code/Test_Definitions/number-verification-verify.feature @@ -1,11 +1,9 @@ - - @NumberVerification_verify Feature: Camara Number Verification API verify # Input to be provided by the implementation to the tests # References to OAS spec schemas refer to schemas specified in -# https://raw.githubusercontent.com/camaraproject/NumberVerification/main/code/API_definitions/number_verification.yaml +# /code/API_definitions/number-verification.yaml # # Implementation indications: # * api_root: API root of the server URL @@ -16,10 +14,8 @@ Feature: Camara Number Verification API verify # * a mobile device with SIM card with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER_HASHED1 # * a mobile device with SIM card with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER_HASHED2 - - Background: Common Number Verification verify setup - Given the resource "/number-verification/v0" as base url + Given the resource "/number-verification/v1" as base url And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" is set to a UUID value @@ -39,7 +35,7 @@ Feature: Camara Number Verification API verify And the response property "$.code" is "INVALID_ARGUMENT" And the response property "$.message" contains a user friendly text And they acquired a valid access token associated with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1 through OIDC authorization code flow - + Examples: | phone_number_value | | string_value | @@ -49,7 +45,6 @@ Feature: Camara Number Verification API verify | 123 | | ++49565456787 | - @NumberVerification_verify100_match_true Scenario: verify phone number NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1, network connection and access token matches NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1 Given they use the base url @@ -78,7 +73,6 @@ Feature: Camara Number Verification API verify Then the response status code is 200 And the response property "$.devicePhoneNumberVerified" is true - @NumberVerification_verify101_match_false Scenario: verify phone number NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER1 but access token is associated with NUMBERVERIFY_VERIFY_MATCH_PHONENUMBER2 Given they use the base url @@ -157,7 +151,7 @@ Feature: Camara Number Verification API verify And the response property "$.message" is "New authentication is required." @NumberVerification_verify203_both_phone_number_and_hashed_in_request - Scenario: verify phone number but no phonenumber in request + Scenario: verify phone number but providing both plain and hashed phone number in the body Given they use the base url And the resource is "/verify" And one of the scopes associated with the access token is number-verification:verify @@ -188,7 +182,6 @@ Feature: Camara Number Verification API verify And the response property "$.status" is 403 And the response property "$.code" is "INVALID_TOKEN_CONTEXT" And the response property "$.message" is "Phone number cannot be deducted from access token context." - @NumberVerification_phone_number_verify205_must_have_used_network_authentication Scenario: verify phone number with valid access token but network authentication was not used diff --git a/documentation/API_documentation/NumberVerification-Readiness-Checklist.md b/documentation/API_documentation/NumberVerification-Readiness-Checklist.md index d00b0b8..dfaa598 100644 --- a/documentation/API_documentation/NumberVerification-Readiness-Checklist.md +++ b/documentation/API_documentation/NumberVerification-Readiness-Checklist.md @@ -1,22 +1,24 @@ # API Readiness Checklist -Checklist for number_verification 1.0.0-rc.1 in release r1.1 +Checklist for number-verification 1.0.0 in release r1.2 | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/number_verification.yaml) | +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/number-verification.yaml) | | 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | | | 3 | Guidelines from ICM applied | O | M | M | M | Y | | | 4 | API versioning convention applied | M | M | M | M | Y | | -| 5 | API documentation | M | M | M | M | Y | Embed documentation into API spec - [link](/code/API_definitions/number_verification.yaml) | -| 6 | User stories | O | O | O | M | tbd | [PR #129](https://github.com/camaraproject/NumberVerification/pull/129/files) | -| 7 | Basic API test cases & documentation | O | M | M | M | tbd | [PR #124](https://github.com/camaraproject/NumberVerification/pull/124/files) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | tbd | [PR #124](https://github.com/camaraproject/NumberVerification/pull/124/files) | -| 9 | Test result statement | O | O | O | M | tbd | link | - +| 5 | API documentation | M | M | M | M | Y | Embedded documentation into API spec - [link](/code/API_definitions/number-verification.yaml) | +| 6 | User stories | O | O | O | M | Y | [get](/documentation/API_documentation/NumberVerification_device_phone_number_User_Story.md) [verify](/documentation/API_documentation/NumberVerification_verify_User_Story.md) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](/code/Test_Definitions/number-verification-verify.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](code/Test_Definitions/number-verification-verify.feature) | +| 9 | Test result statement | O | O | O | M | N | Fall24 EXCEPTION: Test results not available (*) | | 10 | API release numbering convention applied | M | M | M | M | Y | | -| 11 | Change log updated | M | M | M | M | N | [link](/CHANGELOG.md) | -| 12 | Previous public-release was certified | O | O | O | M | Y | | +| 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | +| 12 | Previous public-release was certified | O | O | O | M | Y | [link](https://www.open-gateway.com/operators-map) | + +(*) If you encounter issues with the provided test files (.feature), please create an issue in the API Sub-Project to signal these issues so they can be fixed in a patch release. + To fill the checklist: - in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release.