Merge remote-tracking branch 'refs/remotes/upstream/main' into featur…

…e/cloud-event-when-delete-subscription
camaraproject · Jun 11, 2024 · c307c75 · c307c75
2 parents d3caca4 + bdd6710
commit c307c75
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 23 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,20 +1,56 @@
 # Changelog DeviceStatus
 ## Table of Contents
+- [r0.6](#r06)
 - [v0.5.1](#v051)
 - [v0.5.0](#v050)
 - [v0.5.0-rc](#v050-rc)
 - [v0.4.1](#v041)
 - [v0.2.0](#v020)
 
+# r0.6  
+## Please note:
+- This release contains an alpha version of the API, it should be considered as a draft.
+- There are bug fixes to be expected and incompatible changes in upcoming versions.
+
+## Device Status - v0.6.0-alpha.1
+- API definition **with inline documentation**: 
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/release-0.6/code/API_definitions/device-status.yaml)
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.6/code/API_definitions/device-status.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.6/code/API_definitions/device-status.yaml)
+### Main Changes
+* Endpoints renamed 
+* New response parameter lastStatusTime
+
+### Added
+* Addition of "lastStatusTime" Field by @sachinvodafone in https://github.com/camaraproject/DeviceStatus/pull/146
+* include x-correlator by @fernandopradocabrillo in https://github.com/camaraproject/DeviceStatus/pull/112
+
+### Changed
+* Change endpoint names to comply with guideline by @gmuratk in https://github.com/camaraproject/DeviceStatus/pull/131
+* renaming "EventType"-components to be more clear & update component descriptions by @maxl2287 in https://github.com/camaraproject/DeviceStatus/pull/141
+* Make '+' mandatory for phoneNumber by @bigludo7 in https://github.com/camaraproject/DeviceStatus/pull/144
+
+### Fixed
+* NA
+
+### Removed
+* NA
+
+## New Contributors
+* NA
+
+**Full Changelog**: https://github.com/camaraproject/DeviceStatus/compare/v0.5.1...r0.6
+
+
 # v0.5.1
-**This is a bugfix release for the third alpha version of the CAMARA DeviceStatus API**
+**This is a bugfix release for the third initial version of the CAMARA DeviceStatus API**
 - API definition **with inline documentation**:
   - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/release-0.5.1/code/API_definitions/device-status.yaml)
   - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.1/code/API_definitions/device-status.yaml&nocors)
   - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.1/code/API_definitions/device-status.yaml)
 
 ## Please note:
-- This is an alpha version, it should be considered as a draft.
+- This is an initial version, it should be considered as a draft.
 - There are bug fixes to be expected and incompatible changes in upcoming versions.
 - The release is suitable for implementors, but it is not recommended to use the API with customers in productive environments.
 
@@ -45,15 +81,15 @@
 
 
 # v0.5.0
-**This is the third alpha version of the CAMARA DeviceStatus API**
+**This is the third initial version of the CAMARA DeviceStatus API**
 - API definition **with inline documentation**:
   - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/release-0.5.0/code/API_definitions/device-status.yaml)
   - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.0/code/API_definitions/device-status.yaml&nocors)
   - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.0/code/API_definitions/device-status.yaml)
 
 ## Please note:
 - **This release contains significant changes compared to v0.4.1, and it is not backward compatible**
-- This is an alpha version, it should be considered as a draft.
+- This is an initial version, it should be considered as a draft.
 - There are bug fixes to be expected and incompatible changes in upcoming versions.
 - The release is suitable for implementors, but it is not recommended to use the API with customers in productive environments.
 
@@ -91,7 +127,7 @@
 
 
 # v0.5.0-rc
-**This is the release candidate of v0.5.0 - containing the upcoming 3rd alpha version of the DeviceStatus API**
+**This is the release candidate of v0.5.0 - containing the upcoming 3rd initial version of the DeviceStatus API**
 - API definition **with inline documentation**:
   - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/release-0.5.0-rc/code/API_definitions/device-status.yaml)
   - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.0-rc/code/API_definitions/device-status.yaml&nocors)

diff --git a/README.md b/README.md
@@ -4,6 +4,7 @@
 <a href="https://github.com/camaraproject/DeviceStatus/graphs/contributors" title="Contributors"><img src="https://img.shields.io/github/contributors/camaraproject/DeviceStatus?style=plastic"></a>
 <a href="https://github.com/camaraproject/DeviceStatus" title="Repo Size"><img src="https://img.shields.io/github/repo-size/camaraproject/DeviceStatus?style=plastic"></a>
 <a href="https://github.com/camaraproject/DeviceStatus/blob/main/LICENSE" title="License"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg?style=plastic"></a>
+<a href="https://github.com/camaraproject/DeviceStatus/releases/latest" title="Latest Release"><img src="https://img.shields.io/github/release/camaraproject/DeviceStatus?style=plastic"></a>
 
 # DeviceStatus
 Repository to describe, develop, document and test the DeviceStatus API family
@@ -14,23 +15,30 @@ Repository to describe, develop, document and test the DeviceStatus API family
   * check if a device is losing connection to the network or gets reachable again, and the roaming status.
   * NOTE: The scope of this API family 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 2022
-* Location: virtually  
+* Started: July 2022 
 
-## Meetings
-* Meetings are held virtually
-* Schedule: bi-weekly (odd weeks), Wednesday, 11 AM CET
-* Meeting link: <a href="https://teams.microsoft.com/l/meetup-join/19%3ameeting_NDQwYTlkZjYtOTc0NS00MjA5LWE2YjItMWFjYTczZTM4NTEx%40thread.v2/0?context=%7b%22Tid%22%3a%22bde4dffc-4b60-4cf6-8b04-a5eeb25f5c4f%22%2c%22Oid%22%3a%22389ab01b-6fbd-4e02-8f1a-1be1e09c95e8%22%7d">Microsoft Teams Meeting</a>
+## Release Information
 
-## 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 public release is available here: https://github.com/camaraproject/DeviceStatus/releases/latest
+* For changes see [CHANGELOG.md](https://github.com/camaraproject/DeviceStatus/blob/main/CHANGELOG.md) 
+<!-- * Further release information is available within (link to release tracker page on wiki when available) -->
+<!-- Pre-releases are available in https://github.com/camaraproject/DeviceStatus/releases> -->
 
-* The latest available and released version 0.5.1 of the API is available within the [release-0.5.1 branch](https://github.com/camaraproject/DeviceStatus/tree/release-0.5.1)
+* 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 public release**.
+
+<!-- following part left in for now but could be omitted going forward -->
+* The latest available release version 0.6 (with API version 0.6.0-alpha.1) is available [here](https://github.com/camaraproject/DeviceStatus/tree/r0.6)
   - API definition with inline documentation:
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/release-0.5.1/code/API_definitions/device-status.yaml)
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.1/code/API_definitions/device-status.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/release-0.5.1/code/API_definitions/device-status.yaml) 
+    - OpenAPI [YAML spec file](https://github.com/camaraproject/DeviceStatus/blob/r0.6/code/API_definitions/device-status.yaml)
+    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/r0.6/code/API_definitions/device-status.yaml&nocors)
+    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/DeviceStatus/r0.6/code/API_definitions/device-status.yaml) 
 
-## Contributorship and mailing list
-* To subscribe / unsubscribe to the mailing list of this Sub Project and thus be / resign as Contributor please visit <https://lists.camaraproject.org/g/sp-dst>.
-* A message to all Contributors of this Sub Project can be sent using <[email protected]>.
+## Contributing
+* Meetings
+  * Bi-weekly on Wednesday, 11:00 CET/CEST (08:00 UTC, 09:00 UTC during European DST)
+  * [Registration / Join](https://zoom-lfx.platform.linuxfoundation.org/meeting/93413850406?password=3aeb0f1b-d9f9-42c5-91d8-3d2b20421ef1)
+  * Access [meeting minutes](https://wiki.camaraproject.org/x/5oAuAQ) 
+* Mailing List
+  * Subscribe / Unsubscribe to the mailing list of this Sub Project https://lists.camaraproject.org/g/sp-dst.
+  * A message to the community of this Sub Project can be sent using <[email protected]>.
+
diff --git a/code/API_definitions/device-status.yaml b/code/API_definitions/device-status.yaml
@@ -45,6 +45,8 @@ info:
       - `CONNECTED_DATA`, if device is connected to the network via data usage
       - `NOT_CONNECTED`, if device is not connected to the network
 
+    * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain.
+
     # API Functionality
 
     The API exposes following capabilities:
@@ -103,13 +105,13 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: wip
+  version: 0.6.0-alpha.1
 externalDocs:
   description: Product documentation at CAMARA
   url: https://github.com/camaraproject/
 
 servers:
-  - url: "{apiRoot}/device-status/v0"
+  - url: "{apiRoot}/device-status/v0.6alpha1"
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -155,12 +157,15 @@ paths:
               examples:
                 Connected-With-SMS:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     connectivityStatus: CONNECTED_SMS
                 Connected-With-DATA:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     connectivityStatus: CONNECTED_DATA
                 Not-Connected:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     connectivityStatus: NOT_CONNECTED
         "400":
           $ref: "#/components/responses/Generic400"
@@ -205,16 +210,19 @@ paths:
               examples:
                 No-Country-Name:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     roaming: true
                     countryCode: 901
                     countryName: []
                 Single-Country-Code:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     roaming: true
                     countryCode: 262
                     countryName: ["DE"]
                 Multiple-Country-Codes:
                   value:
+                    lastStatusTime: "2024-02-20T10:41:38.657Z"
                     roaming: true
                     countryCode: 340
                     countryName: ["BL", "GF", "GP", "MF", "MQ"]
@@ -473,13 +481,21 @@ components:
       required:
         - roaming
       properties:
+        lastStatusTime:
+          $ref: "#/components/schemas/LastStatusTime"
         roaming:
           $ref: "#/components/schemas/ActiveRoaming"
         countryCode:
           $ref: "#/components/schemas/CountryCode"
         countryName:
           $ref: "#/components/schemas/CountryName"
 
+    LastStatusTime:
+      description: Last time that the associated device roaming status/connectivity was updated
+      type: string
+      format: date-time
+      example: "2024-02-20T10:41:38.657Z"
+
     ActiveRoaming:
       description: Roaming status. True, if it is roaming
       type: boolean
@@ -489,6 +505,8 @@ components:
       required:
         - connectivityStatus
       properties:
+        lastStatusTime:
+          $ref: "#/components/schemas/LastStatusTime"
         connectivityStatus:
           $ref: "#/components/schemas/ConnectivityStatus"
 
@@ -767,7 +785,7 @@ components:
       type: string
       format: uuid
       description: Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server
-      example: qs15-h556-rt89-1298
+      example: 550e8400-e29b-41d4-a716-446655440000
 
     CloudEvent:
       description: The notification callback