diff --git a/CHANGELOG.md b/CHANGELOG.md index da9dfd5..f1337a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,54 @@ ## Table of Contents +- [r3.2](#r32) **Fall 25** - [r3.1](#r31) -- **[r2.2](#r22)** +- [r2.2](#r22) **Spring 25** - [r2.1](#r21) -- **[r1.2](#r12)** +- [r1.2](#r12) - [r1.1](#r11) **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.** +# r3.2 +## Release Notes + +This public release contains the definition and documentation of +* device-swap v1.0.0 + +The API definition(s) are based on +* Commonalities v0.6.0 +* Identity and Consent Management v0.4.0 + +## device-swap v1.0.0 + +This is the first **release** of the device-swap API version v1.0.0. + +- 1.0.0 Device Swap API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceSwap/blob/r3.2/code/API_definitions/device-swap.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.2/code/API_definitions/device-swap.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.2/code/API_definitions/device-swap.yaml) + +Changes included in v1.0.0 compared to v0.2.0: + +### Added +N/A + +### Changed +* Update pattern for x-correlator by @bigludo7 in https://github.com/camaraproject/DeviceSwap/pull/53 +* Rename test file to use valid operation: checkDeviceSwap.feature (instead of device-swap-check.feature) and retrieveDeviceSwapDate.feature (instead of device-swap-retrieve-date.feature) by @bigludo7 in https://github.com/camaraproject/DeviceSwap/pull/59 +* Update ErrorInfo attribute description by by @bigludo7 in https://github.com/camaraproject/DeviceSwap/pull/69 + +### Fixed +N/A +### Removed +N/A + +## New Contributors +N/A + +**Full Changelog**: https://github.com/camaraproject/DeviceSwap/compare/r2.2...r3.2 + # r3.1 ## Release Notes diff --git a/README.md b/README.md index f298b15..87af02e 100644 --- a/README.md +++ b/README.md @@ -19,16 +19,16 @@ Incubating API Repository to evolve and maintain the definitions and documentati * understand if the MSISDN has had a change of device in the last 30 days. * NOTE: The scope of these APIs should be limited (at least at a first stage) to 4G and 5G. * Describe, develop, document and test the APIs (with 1-2 Telcos) -* Started: July 2024 +* Started: July 2024 * * Incubating stage since: June 2025 ## Release Information * 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**. -* `NEW`: Pre-release r3.1 with version 1.0.0-rc.1 of the API device-swap is available [here](https://github.com/camaraproject/DeviceSwap/tree/r3.1). -- 1.0.0-rc.1 Device Swap API definition **with inline documentation**: - - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceSwap/blob/r3.1/code/API_definitions/device-swap.yaml) - - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.1/code/API_definitions/device-swap.yaml&nocors) - - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.1/code/API_definitions/device-swap.yaml) +* `NEW`: Public release r3.2 with **version 1.0.0** of the API device-swap is available [here](https://github.com/camaraproject/DeviceSwap/tree/r3.2). +- 1.0.0 Device Swap API definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceSwap/blob/r3.2/code/API_definitions/device-swap.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.2/code/API_definitions/device-swap.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/DeviceSwap/r3.2/code/API_definitions/device-swap.yaml) * The latest public release is available here: https://github.com/camaraproject/DeviceSwap/releases/latest * Other releases of this sub project are available in https://github.com/camaraproject/DeviceSwap/releases * For changes see [CHANGELOG.md](https://github.com/camaraproject/DeviceSwap/blob/main/CHANGELOG.md) @@ -43,5 +43,3 @@ Incubating API Repository to evolve and maintain the definitions and documentati * Mailing List * Subscribe / Unsubscribe to the mailing list of this Sub Project . * A message to the community of this Sub Project can be sent using . - - diff --git a/code/API_definitions/device-swap.yaml b/code/API_definitions/device-swap.yaml index fcd8155..735941b 100644 --- a/code/API_definitions/device-swap.yaml +++ b/code/API_definitions/device-swap.yaml @@ -63,7 +63,7 @@ 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.6 externalDocs: @@ -71,7 +71,7 @@ externalDocs: url: https://github.com/camaraproject/DeviceSwap servers: - - url: '{apiRoot}/device-swap/vwip' + - url: '{apiRoot}/device-swap/v1' variables: apiRoot: default: http://localhost:9091 @@ -213,13 +213,12 @@ components: latestDeviceChange: type: string format: date-time - description: Timestamp of latest device swap performed. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) + description: Timestamp of latest device swap performed. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. nullable: true example: "2023-07-03T14:27:08.312+02:00" monitoredPeriod: type: integer description: Timeframe in days for device change supervision for the phone number. It could be valued in the response if the latest Device swap occurred before this monitored period. - example: 120 CreateDeviceSwapDate: type: object @@ -260,15 +259,15 @@ components: - code - message properties: + message: + type: string + description: A human-readable description of what the event represents status: type: integer description: HTTP response status code code: type: string - description: Code given to this error - message: - type: string - description: Detailed error description + description: A human-readable code to describe the error responses: Generic400: description: Bad Request diff --git a/code/Test_definitions/device-swap-checkDeviceSwap.feature b/code/Test_definitions/device-swap-checkDeviceSwap.feature index 00f4f00..1084481 100644 --- a/code/Test_definitions/device-swap-checkDeviceSwap.feature +++ b/code/Test_definitions/device-swap-checkDeviceSwap.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Device Swap API, wip - Operation checkDeviceSwap +Feature: CAMARA Device Swap API, v1.0.0 - Operation checkDeviceSwap # Input to be provided by the implementation to the tester # @@ -8,7 +8,7 @@ Feature: CAMARA Device Swap API, wip - Operation checkDeviceSwap # References to OAS spec schemas refer to schemas specifies in device-swap.yaml Background: Common checkDeviceSwap setup - Given the resource "device-swap/vwip/check" + Given the resource "device-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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature b/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature index f3adcc4..e96e006 100644 --- a/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature +++ b/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Device Swap API, wip - Operation retrieveDeviceSwapDate +Feature: CAMARA Device Swap API, v1.0.0 - Operation retrieveDeviceSwapDate # Input to be provided by the implementation to the tester # @@ -8,7 +8,7 @@ Feature: CAMARA Device Swap API, wip - Operation retrieveDeviceSwapDate # References to OAS spec schemas refer to schemas specifies in device-swap.yaml. Background: Common retrieveDeviceSwapDate setup - Given the resource "device-swap/vwip/retrieve-date" + Given the resource "device-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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/documentation/API_documentation/device-swap-API-Readiness-Checklist.md b/documentation/API_documentation/device-swap-API-Readiness-Checklist.md index ee74897..cd6daad 100644 --- a/documentation/API_documentation/device-swap-API-Readiness-Checklist.md +++ b/documentation/API_documentation/device-swap-API-Readiness-Checklist.md @@ -1,19 +1,19 @@ # API Readiness Checklist -Checklist for device-swap v1.0.0-rc.1 in r3.1 +Checklist for device-swap v1.0.0 in r3.2 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| | 1 | API definition | M | M | M | M | Y | [link](code/API_definitions/device-swap.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 | v1.0.0-rc.1 | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/Commonalities/releases/tag/r3.3) | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.3) | +| 4 | API versioning convention applied | M | M | M | M | Y | v1.0.0 | | 5 | API documentation | M | M | M | M | Y | Embedded documentation into API spec - [link](/code/API_definitions/device-swap.yaml) | | 6 | User stories | O | O | O | M | Y | [check](/documentation/API_documentation/device-swap_check_User_Story.md) [retrieve](/documentation/API_documentation/device-swap_retrieve_User_Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [check](/code/Test_definitions/checkDeviceSwap.feature) [retrieve](/code/Test_definitions/retrieveDeviceSwapDate.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [check](/code/Test_definitions/checkDeviceSwap.feature) [retrieve](/code/Test_definitions/retrieveDeviceSwapDate.feature) | -| 9 | Test result statement | O | O | O | M | N | To be provided | -| 10 | API release numbering convention applied | M | M | M | M | Y | r3.1 | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [check](/code/Test_definitions/device-swap-checkDeviceSwap.feature) [retrieve](/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [check](/code/Test_definitions/device-swap-checkDeviceSwap.feature) [retrieve](/code/Test_definitions/device-swap-retrieveDeviceSwapDate.feature) | +| 9 | Test result statement | O | O | O | M | N | See issue [#68](https://github.com/camaraproject/DeviceSwap/issues/68) | +| 10 | API release numbering convention applied | M | M | M | M | Y | r3.2 | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public release was certified | O | O | O | M | N | | | 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81166764/DeviceSwap+API+description) |