diff --git a/CHANGELOG.md b/CHANGELOG.md index cd6e292..29b2c4a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,10 @@ # Changelog CAMARA SimSwap -## Table of Contents +## Table of contents -- [r1.1](#r11) -- [v0.4.0](#v040) +- **[r1.2](#r12)** +- **[r1.1](#r11)** +- **[v0.4.0](#v040)** **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.** @@ -13,7 +14,85 @@ The below sections record the changes for each API version in each release as fo * for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release * for a public API version, the consolidated changes since the release of the previous public API version -# r1.1 - rc +# r1.2 + +## Release Notes + +This release contains the definition and documentation of +* sim-swap 1.0.0 +* sim-swap-subscriptions 0.1.0 + +The API definition(s) are based on +* Commonalities v0.4.0 +* Identity and Consent Management v0.2.0 + +## sim-swap 1.0.0 + +**sim-swap 1.0.0 is the public release for v1.0.0 of the Sim Swap API.** + +- API definition **with inline documentation**: + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swap.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swaps.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/SimSwap/blob/r1.2/code/API_definitions/sim-swap.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. + + +### Added +* User Story in documentation/API_documentation directory by @jgarciahospital [PR125](https://github.com/camaraproject/SimSwap/pull/125) +* Test Definition in Test_Definitions directory by @fernandopradocabrillo [PR70](https://github.com/camaraproject/SimSwap/pull/70) +* Added the API name `sim-swap` as a scope to request access to both available endpoints by @AxelNennker in https://github.com/camaraproject/SimSwap/pull/103 + +### Changed +* Made response properties `latestSimChange` and `swapped` required since they will always be returned by @fernandopradocabrillo in https://github.com/camaraproject/SimSwap/pull/97 +* Updated pattern to make the '+' mandatory for phoneNumber by @bigludo7 in https://github.com/camaraproject/SimSwap/pull/100 +* Replaced "MSISDN" with "phone number" in descriptions to follow Commonalities guidelines by @gregory1g in https://github.com/camaraproject/SimSwap/pull/116 +* Removed unused errors and align with Commonalities error definitions by @fernandopradocabrillo in https://github.com/camaraproject/SimSwap/pull/126 + +### Fixed +* N/A + +### Removed +* N/A + +## New Contributors +* N/A + +## Sim Swap Subscriptions v0.1.0 + +**sim-swap-subscriptions v0.1.0 is the first initial version for the CAMARA Sim Swap Subscriptions API** + +- API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/SimSwap/blob/r1.2/code/API_definitions/sim-swap-subscriptions.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swap-subscriptions.yaml&nocors) + - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swap-subscriptions.yaml) + +**Main Changes** +* Initial contribution of the API definition for Sim Swap Subscriptions allowing API consumers to subscribe to get notified when a sim swap occurs on a device. +* 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 +* Test cases added. + +### Added +* Initial yaml contribution by @bigludo7 [PR60](https://github.com/camaraproject/SimSwap/pull/60) +* Test Definition in Test_Definitions directory by @bigludo7 [PR147](https://github.com/camaraproject/SimSwap/pull/147) + +### Changed +* N/A + +### Fixed +* N/A + +### Removed +* N/A + +## New Contributors +* N/A + +**Full Changelog**: https://github.com/camaraproject/SimSwap/compare/v0.4.0...r1.2 + +# r1.1 ## Release Notes @@ -36,14 +115,13 @@ This version contains significant changes compared to v0.4.0, and it is not back - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.1/code/API_definitions/sim_swap.yaml) ### Added - * User Story in documentation/API_documentation directory by @jgarciahospital [PR125](https://github.com/camaraproject/SimSwap/pull/125) * Test Definition in Test_Definitions directory by @fernandopradocabrillo [PR70](https://github.com/camaraproject/SimSwap/pull/70) * add API-Name aka wild-card scope by @AxelNennker in https://github.com/camaraproject/SimSwap/pull/103 ### Changed * Make response properties "latestSimChange" and "swapped" required since they will always be returned [Issue 96](https://github.com/camaraproject/SimSwap/issues/96) -* Update SIM Swap & SIM Swap notification subscription yaml to make the '+' mandatory for phoneNumber by @bigludo7 in https://github.com/camaraproject/SimSwap/pull/100 +* Updated pattern to make the '+' mandatory for phoneNumber by @bigludo7 in https://github.com/camaraproject/SimSwap/pull/100 * phone number instead of MSISDN to follow communalities guidelines by @gregory1g in https://github.com/camaraproject/SimSwap/pull/116 * Remove unused errors and align with commonalities errors by @fernandopradocabrillo in https://github.com/camaraproject/SimSwap/pull/126 @@ -62,7 +140,6 @@ This version contains significant changes compared to v0.4.0, and it is not back ## Please note: -- This is an **alpha version**, it should be considered as a **draft** - There are bug fixes to be expected and incompatible changes in upcoming versions - The API version is suitable for test implementations and has the purpose to collect feedback for its further development. It should not be used with customers in productive environments. diff --git a/README.md b/README.md index 838594b..45240c0 100644 --- a/README.md +++ b/README.md @@ -21,19 +21,21 @@ Repository to describe, develop, document and test the SimSwap API family ## 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 is [r1.1](https://github.com/camaraproject/SimSwap/releases/tag/r1.1). It contains: - * **sim-swap v1.0.0-rc.1** - * **This is the release candidate of the first stable version of the Sim Swap API**. It is suitable for implementors. - * API definitions (with inline documentation): - * OpenAPI [YAML](https://github.com/camaraproject/SimSwap/blob/r1.1/code/API_definitions/sim_swap.yaml) - * [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.1/code/API_definitions/sim_swap.yaml&nocors) - * [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.1/code/API_definitions/sim_swap.yaml) - * sim-swap-swap-subscriptions v0.1.0-alpha.1 - * This is the first alpha version for CAMARA Sim Swap subscription API. It should considered as a draft. - * API definitions (with inline documentation): - * OpenAPI [YAML](https://github.com/camaraproject/SimSwap/blob/r1.1/code/API_definitions/sim-swap-subscriptions.yaml) - * [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.1/code/API_definitions/sim-swap-subscriptions.yaml&nocors) - * [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.1/code/API_definitions/sim-swap-subscriptions.yaml) +* `NEW`: Release r1.2 features following APIs: + * version 1.0.0 of the **API sim-swap** - available [here](https://github.com/camaraproject/SimSwap/tree/r1.2) + * API definitions **with inline documentation**): + * OpenAPI [YAML](https://github.com/camaraproject/SimSwap/blob/r1.2/code/API_definitions/sim_swap.yaml) + * [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim_swap.yaml&nocors) + * [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim_swap.yaml) + * version 0.1.0 of the **API sim-swap-subscriptions** - available [here](https://github.com/camaraproject/SimSwap/tree/r1.2) + * API definitions **with inline documentation**: + * OpenAPI [YAML](https://github.com/camaraproject/SimSwap/blob/r1.2/code/API_definitions/sim-swap-subscriptions.yaml) + * [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swap-subscriptions.yaml&nocors) + * [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/SimSwap/r1.2/code/API_definitions/sim-swap-subscriptions.yaml) + + * The latest public release is available here: https://github.com/camaraproject/SimSwap/releases/latest + * Other releases of this sub project are available in https://github.com/camaraproject/SimSwap/releases + * For changes see [CHANGELOG.md](https://github.com/camaraproject/Simswap/blob/main/CHANGELOG.md) ## Contributing diff --git a/code/API_definitions/sim-swap-subscriptions.yaml b/code/API_definitions/sim-swap-subscriptions.yaml index 3922935..7c0d685 100644 --- a/code/API_definitions/sim-swap-subscriptions.yaml +++ b/code/API_definitions/sim-swap-subscriptions.yaml @@ -61,14 +61,15 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: 0.1.0 x-camara-commonalities: 0.4.0 externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/ servers: - - url: '{apiRoot}/sim-swap-subscriptions/v0.1alpha1' + - url: '{apiRoot}/sim-swap-subscriptions/v0.1' + variables: apiRoot: default: http://localhost:9091 diff --git a/code/API_definitions/sim-swap.yaml b/code/API_definitions/sim-swap.yaml index 827fbb7..481c12d 100644 --- a/code/API_definitions/sim-swap.yaml +++ b/code/API_definitions/sim-swap.yaml @@ -73,13 +73,13 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip + version: 1.0.0 x-camara-commonalities: 0.4.0 externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/SimSwap servers: - - url: "{apiRoot}/sim-swap/v1rc1" + - url: "{apiRoot}/sim-swap/v1" variables: apiRoot: default: http://localhost:9091 diff --git a/code/Test_definitions/checkSimSwap.feature b/code/Test_definitions/check-sim-swap.feature similarity index 97% rename from code/Test_definitions/checkSimSwap.feature rename to code/Test_definitions/check-sim-swap.feature index 41db871..399b6d1 100644 --- a/code/Test_definitions/checkSimSwap.feature +++ b/code/Test_definitions/check-sim-swap.feature @@ -5,17 +5,16 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation checkSimSwap # Testing assets: # # References to OAS spec schemas refer to schemas specifies in sim_swap.yaml, version 1.0.0 - - check if SIM swap has been performed during a past period + # + # check if SIM swap has been performed during a past period Background: Common checkSimSwap setup - Given the resource "sim-swap/v0/check" + Given the resource "sim-swap/v1/check" 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 And the request body is set by default to a request body compliant with the schema - # This first scenario serves as a minimum, not testing any specific verificationResult @check_sim_swap_1_generic_success_scenario Scenario: Common validations for any sucess scenario @@ -29,7 +28,7 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation checkSimSwap # Scenarios testing specific situations @check_sim_swap_2_valid_sim_swap_no_max_age - Scenario: Check that the response shows that the SIM has been swapped + Scenario: Check that the response shows that the SIM has been swapped using default value for maxAge Given the request header "Authorization" is set to a valid access token from which a phone number connected to the Operator's network can be deducted And the SIM for this phone number has been swapped in the last 240 hours When the request "checkSimSwap" is sent @@ -37,7 +36,7 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation checkSimSwap And the value of response property "$.swapped" == true @check_sim_swap_3_valid_sim_swap_max_age - Scenario Outline: Check that the response shows that the SIM has been swapped + Scenario Outline: Check that the response shows that the SIM has been swapped - maxAge is provided in the request Given the request header "Authorization" is set to a valid access token from which a phone number connected to the Operator's network can be deducted And the SIM for this phone number has been swapped in the last "" And the "maxAge" request body property is set to a value equal or greater than "" within the allowed range @@ -64,7 +63,7 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation checkSimSwap Scenario: Check that the response shows that the SIM has not been swapped when the last swap was before the maxAge field Given the request header "Authorization" is set to a valid access token from which a phone number connected to the Operator's network can be deducted And the request body property "maxAge" is set to the number of hours since the last SIM swap minus 1 - And the last swap for this phone number's SIM was more than "maxAge" hours ago + And the last swap for this phone number's SIM was more than "maxAge" hours ago When the request "checkSimSwap" is sent Then the response status code is 200 And the value of response property "$.swapped" == false diff --git a/code/Test_definitions/retrieveSimSwapDate.feature b/code/Test_definitions/retrieve-sim-swap-date.feature similarity index 98% rename from code/Test_definitions/retrieveSimSwapDate.feature rename to code/Test_definitions/retrieve-sim-swap-date.feature index a70daee..7fd57c5 100644 --- a/code/Test_definitions/retrieveSimSwapDate.feature +++ b/code/Test_definitions/retrieve-sim-swap-date.feature @@ -5,11 +5,11 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation retrieveSimSwapDate # Testing assets: # # References to OAS spec schemas refer to schemas specifies in sim_swap.yaml, version 1.0.0 - - Get timestamp of last MSISDN <-> IMSI pairing change for the provided phone number. + # + # Get timestamp of last MSISDN <-> IMSI pairing change for the provided phone number. Background: Common retrieveSimSwapDate setup - Given the resource "sim-swap/v0/retrieve-date" + Given the resource "sim-swap/v1/retrieve-date" 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 @@ -25,7 +25,6 @@ Feature: CAMARA SIM Swap API, 1.0.0 - Operation retrieveSimSwapDate And the response header "x-correlator" has same value as the request header "x-correlator" And the response body complies with the OAS schema at "/components/schemas/SimSwapInfo" - # Scenarios testing specific situations @retrieve_sim_swap_date_2_valid_sim_swap diff --git a/code/Test_definitions/sim-swap-subscriptions.feature b/code/Test_definitions/sim-swap-subscriptions.feature index 55ee0d9..e9ba206 100644 --- a/code/Test_definitions/sim-swap-subscriptions.feature +++ b/code/Test_definitions/sim-swap-subscriptions.feature @@ -9,7 +9,7 @@ Feature: CAMARA sim swap subscriptions API, v0.1.0 # References to OAS spec schemas refer to schemas specifies in sim-swap-subscriptions.yaml, version v0.1.0 Background: Common subscriptions setup - Given the resource "/sim-swap-subscriptions/v0/subscriptions" as BaseURL | + Given the resource "/sim-swap-subscriptions/v0.1/subscriptions" as BaseURL | 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/documentation/API_documentation/sim-swap-API-Readiness-Checklist.md b/documentation/API_documentation/sim-swap-API-Readiness-Checklist.md index 330a0cd..b42ca3e 100644 --- a/documentation/API_documentation/sim-swap-API-Readiness-Checklist.md +++ b/documentation/API_documentation/sim-swap-API-Readiness-Checklist.md @@ -9,13 +9,15 @@ Checklist for sim-swap 1.0.0 in r1.2 | 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/sim-swap.yaml) | -| 6 | User stories | O | O | O | M | Y | [check](documentation/API_documentation/SIM-Swap_check_User_Story.md) [retrieve](documentation/API_documentation/SIM-Swap_retrieve_User_Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [PR#70](https://github.com/camaraproject/SimSwap/pull/70) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [PR#70](https://github.com/camaraproject/SimSwap/pull/70) | -| 9 | Test result statement | O | O | O | M | N | | +| 6 | User stories | O | O | O | M | Y | [check](/documentation/API_documentation/SIM-Swap_check_User_Story.md) [retrieve](/documentation/API_documentation/SIM-Swap_retrieve_User_Story.md) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [check](/code/Test_definitions/check-sim-swap.feature) [retrieve](/code/Test_definitions/retrieve-sim-swap-date.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [check](/code/Test_definitions/check-sim-swap.feature) [retrieve](/code/Test_definitions/retrieve-sim-swap-date.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 | Y | [link](/CHANGELOG.md) | -| 12 | Previous public release was certified | O | O | O | M | N | | +| 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. diff --git a/documentation/API_documentation/sim-swap-subscriptions-API-Readiness-Checklist.md b/documentation/API_documentation/sim-swap-subscriptions-API-Readiness-Checklist.md index 847a548..38dc28c 100644 --- a/documentation/API_documentation/sim-swap-subscriptions-API-Readiness-Checklist.md +++ b/documentation/API_documentation/sim-swap-subscriptions-API-Readiness-Checklist.md @@ -1,19 +1,27 @@ # API Readiness Checklist -Checklist for sim-swap-subscriptions 0.1.0-alpha.1 in r1.1 +Checklist for sim-swap-subscriptions 0.1.0 in r1.2 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | -|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| +|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|------| | 1 | API definition | M | M | M | M | Y | [link](code/API_definitions/sim-swap-subscriptions.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | Y | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | Y | -| 4 | API versioning convention applied | M | M | M | M | Y | Y | -| 5 | API documentation | M | M | M | M | Y | contained in API definition | -| 6 | User stories | O | O | O | M | Y | Not Relevant (NR) | -| 7 | Basic API test cases & documentation | O | M | M | M | N | NR | -| 8 | Enhanced API test cases & documentation | O | O | O | M | N | NR | -| 9 | Test result statement | O | O | O | M | N | NR | -| 10 | API release numbering convention applied | M | M | M | M | Y | Y | -| 11 | Change log updated | M | M | M | M | N | [link](/CHANGELOG.md) | +| 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 | Embedded documentation into API spec - [link](/code/API_definitions/sim-swap.yaml) | +| 6 | User stories | O | O | O | M | N | | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/sim-swap-subscriptions.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | N | | +| 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 | N | | -| 12 | Previous public release was certified | O | O | O | M | N | NR | \ No newline at end of file +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. +- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, a "N" (no) or a "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release. +- in the Comments column, provide the link to the asset once available, and any other relevant comments. + +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. + +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/x/HQBFAQ)