diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ffefd5..4c65a23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Table of contents +- **[r3.1](#r31) Fall25** - **[r2.4](#r24) Spring25** - ~~[r2.3](#r23)~~ - **[r2.2](#r22)** @@ -22,6 +23,44 @@ The below sections record the changes for each API version in each release as fo * for subsequent release-candidate(s), only the delta to the previous release-candidate * for a public release, the consolidated changes since the previous public release +# r3.1 + +This **public release** contains the definition and documentation of +* number-verification 2.1.0-rc.1 + +The API definition(s) are based on +* Commonalities v0.6.0-rc.1 +* Identity and Consent Management v0.4.0-rc.1 + +## number-verification 2.1.0-rc.1 + +**number-verification 2.1.0-rc.1 is the first pre-release for v2.0.0-rc.1 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/r3.1/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml) + +### Added + +- Add pattern validation for hashedPhoneNumber by @ravindrapalaskar17 in https://github.com/camaraproject/NumberVerification/pull/188 +- Documented Error Responses info.description section by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/199 +- Include documentation to use with JWT-bearer auth flow by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206 + +### Changed + +- Update x-correlator format by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/200 +- Update test plan by @fernandopradocabrilo in https://github.com/camaraproject/NumberVerification/pull/204 + +### Removed + +- Remove AUTHENTICATION_REQUIRED error by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206 + +## New Contributors +* @ravindrapalaskar17 made their first contribution in https://github.com/camaraproject/NumberVerification/pull/188 + +**Full Changelog**: https://github.com/camaraproject/NumberVerification/compare/r2.4...r3.1 + # r2.4 ## Release Notes diff --git a/README.md b/README.md index 47bb24c..1ab7862 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,13 @@ Incubating API Repository to evolve and maintain the definitions and documentati * 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 public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4) +* **NEW**: The pre-release r3.1 with version 2.1.0-rc.1 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r3.1) + - 2.1.0-rc.1 Number Verification definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml) + +* The latest public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4) - 2.0.0 Number Verification definition **with inline documentation**: - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.4/code/API_definitions/number-verification.yaml) - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml&nocors) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 9a85b1e..b894a66 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -27,7 +27,10 @@ info: ## Authentication Request with a temporary token If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication. - The API Consumer sends the temporary token to their backend which sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter "login_hint=operatortoken:". + The API Consumer sends the temporary token to their backend which either: + - Sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter `login_hint=operatortoken:`. + - Or sends a JWT-Bearer token request as described in [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with the TS.43 token in the `sub` claim of the JWT assertion with the format `"operatortoken:"`. + How the API Consumers get a TS.43 temporary token and how this token is sent to their backend, is out-of-scope of the API definition. ## Authentication Request without a temporary token @@ -80,8 +83,8 @@ info: As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. - version: wip - x-camara-commonalities: 0.5 + version: 2.1.0-rc.1 + x-camara-commonalities: 0.6 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -89,7 +92,7 @@ externalDocs: description: Project documentation at CAMARA url: https://github.com/camaraproject/NumberVerification servers: - - url: '{apiRoot}/number-verification/vwip' + - url: '{apiRoot}/number-verification/v2rc1' variables: apiRoot: default: http://localhost:9091 @@ -287,20 +290,13 @@ components: code: enum: - UNAUTHENTICATED - - AUTHENTICATION_REQUIRED examples: GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated + description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - GENERIC_401_AUTHENTICATION_REQUIRED: - description: New authentication is needed, authentication is no longer valid - value: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required. + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. PhoneNumberVerificationPermissionDenied403: description: | Client does not have sufficient permission. diff --git a/code/Test_Definitions/number-verification-phoneNumberShare.feature b/code/Test_Definitions/number-verification-phoneNumberShare.feature index 92bc21a..6e85f53 100644 --- a/code/Test_Definitions/number-verification-phoneNumberShare.feature +++ b/code/Test_Definitions/number-verification-phoneNumberShare.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare +Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberShare # Input to be provided by the implementation to the tester # @@ -10,7 +10,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare Background: Common phoneNumberShare setup - Given the resource "/number-verification/vwip" as base url + Given the resource "/number-verification/v2rc1" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_Definitions/number-verification-phoneNumberVerify.feature b/code/Test_Definitions/number-verification-phoneNumberVerify.feature index aa80c47..3ab3d9a 100644 --- a/code/Test_Definitions/number-verification-phoneNumberVerify.feature +++ b/code/Test_Definitions/number-verification-phoneNumberVerify.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify +Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberVerify # Input to be provided by the implementation to the tester # @@ -11,7 +11,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify Background: Common phoneNumberVerify setup - Given the resource "/number-verification/vwip" as base url + Given the resource "/number-verification/v2rc1" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md index 2cbc18c..04934d5 100644 --- a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md +++ b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md @@ -1,21 +1,22 @@ # API Readiness Checklist -Checklist for number-verification v2.0.0 in release r2.4 +Checklist for number-verification v2.1.0-rc.1 in release r3.1 | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| -| 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 | [r2.3](https://github.com/camaraproject/Commonalities/releases/tag/r2.3) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r2.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r2.3) | +| 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 | [r3.2](https://github.com/camaraproject/Commonalities/releases/tag/r3.2) | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2) | | 4 | API versioning convention applied | M | M | M | M | Y | | | 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 | see [issue #166](https://github.com/camaraproject/NumberVerification/issues/166) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](/code/Test_Definitions/number-verification-phoneNumberVerify.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](code/Test_Definitions/number-verification-phoneNumberVerify.feature) | +| 9 | Test result statement | O | O | O | M | N | | | 10 | API release numbering convention applied | M | M | M | 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) | +| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81134263/NumberVerification+API+description) | To fill the checklist: