From 8a99a02c487dc886818651f1b325db85af6c073f Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Mon, 5 Feb 2024 10:04:01 +0100 Subject: [PATCH 1/4] Update API-design-guidelines.md Add subscriptionMaxEvents --- documentation/API-design-guidelines.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index f2390e65..c578bb01 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -45,6 +45,8 @@ This document captures guidelines for the API design in CAMARA project. These gu - [11.4 Response Structure](#114-response-structure) - [11.5 Data Definitions](#115-data-definitions) - [11.5.1 Usage of discriminator](#1151-usage-of-discriminator) + - [Inheritance](#inheritance) + - [Polymorphism](#polymorphism) - [11.6 OAuth Definition](#116-oauth-definition) - [12. Subscription, Notification \& Event](#12-subscription-notification--event) - [12.1 Subscription](#121-subscription) @@ -1313,6 +1315,7 @@ The Following table provides `/subscriptions` attributes | subscriptionExpireTime | string - date-time| Date when the event subscription should end. Provided by API requester. The Server may reject the subscription if the period requested do not comply with Telco Operator policies (i.e. to avoid unlimited time subscriptions). In this case server returns exception 403 "SUBSCRIPTION_PERIOD_NOT_ALLOWED" | optional | | startsAt | string - date-time| Date when the event subscription will begin/began. This attribute must not be present in the `POST` request as it is provided by API server. It must be present in `GET` endpoints | optional | | expiresAt | string - date-time| Date when the event subscription will expire. This attribute must not be present in the `POST` request as it is provided by API server. | optional | +| subscriptionMaxEvents | integer | Identifies the maximum number of event reports to be generated - Once this number reached, the subscription ends | optional | | subscriptionDetail | object | Object defined for each event subscription depending on the event - it could be for example the ueID targeted by the subscription | optional | @@ -1342,17 +1345,20 @@ Following Error code must be present: ##### Termination for resource-based (explicit) subscription -3 scenarios of subscription termination are possible (business conditions may apply): +4 scenarios of subscription termination are possible (business conditions may apply): * case1: subscriptionExpireTime has been provided in the request and reached. The operator in this case has to terminate the subscription. -* case2: subscriber requests the `DELETE` operation for the subscription (if the subscription did not have a subscriptionExpireTime or before subscriptionExpireTime expires). -* case3: subscription ends on operator request. +* case2: subscriptionMaxEvents has been provided in the request and reached. The operator in this case has to terminate the subscription. +* case3: subscriber requests the `DELETE` operation for the subscription (if the subscription did not have a subscriptionExpireTime or before subscriptionExpireTime expires). +* case4: subscription ends on operator request. -It could be useful to provide a mechanism to inform subscriber for case3 (and probably case1). In this case, a specific event type could be used. +It could be useful to provide a mechanism to inform subscriber for all case. In this case, a specific event type could be used. -_Termination rules regarding subscriptionExpireTime usage_ -* When client side providing a `subscriptionExpireTime`, service side has to terminate the subscription without expecting a `DELETE` operation. -* When the `subscriptionExpireTime` is not provided, client side has to trigger a `DELETE` operation to terminate it. +_Termination rules regarding subscriptionExpireTime & subscriptionMaxEvents usage_ +* When client side providing a `subscriptionExpireTime` and/or `subscriptionMaxEvents` service side has to terminate the subscription without expecting a `DELETE` operation. +* If both `subscriptionExpireTime` and `subscriptionMaxEvents` are provided, the subscription will end when the first one is reached. +* When the `subscriptionExpireTime` and `subscriptionMaxEvents` are not provided, client side has to trigger a `DELETE` operation to terminate it. +* It is perfectly valid for client side to trigger a DELETE operation before `subscriptionExpireTime` and/or `subscriptionMaxEvents` reached. ##### Resource-based (explicit) example @@ -1449,7 +1455,8 @@ For consistency across CAMARA APIs, the uniform CloudEvents model must be used w Note: For operational and troubleshooting purposes it is relevant to accommodate use of `X-Correlator` header attribute. API listener implementations have to be ready to support and receive this data. -Specific event notification type "subscription-ends" is defined to inform listener about subscription termination. It is used when the subscription expire time (required by the requester) has been reached or if the API server has to stop sending notification prematurely. For this specific event, the `data` must feature `terminationReason` attribute. +Specific event notification type "subscription-ends" is defined to inform listener about subscription termination. It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notification prematurely. For this specific event, the `data` must feature `terminationReason` attribute. +Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example if a client request a `subscriptionMaxEvents` to 2, later, received 2 notification, then a third notification will be send for "subscription-ends") #### Error definition for event notification From 188cd6df1a23a7a54a097934023c8a955533b481 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 13 Feb 2024 15:03:56 +0100 Subject: [PATCH 2/4] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index c578bb01..e7da7ddf 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1315,7 +1315,7 @@ The Following table provides `/subscriptions` attributes | subscriptionExpireTime | string - date-time| Date when the event subscription should end. Provided by API requester. The Server may reject the subscription if the period requested do not comply with Telco Operator policies (i.e. to avoid unlimited time subscriptions). In this case server returns exception 403 "SUBSCRIPTION_PERIOD_NOT_ALLOWED" | optional | | startsAt | string - date-time| Date when the event subscription will begin/began. This attribute must not be present in the `POST` request as it is provided by API server. It must be present in `GET` endpoints | optional | | expiresAt | string - date-time| Date when the event subscription will expire. This attribute must not be present in the `POST` request as it is provided by API server. | optional | -| subscriptionMaxEvents | integer | Identifies the maximum number of event reports to be generated - Once this number reached, the subscription ends | optional | +| subscriptionMaxEvents | integer | Identifies the maximum number of event reports to be generated (>=1) - Once this number is reached, the subscription ends | optional | | subscriptionDetail | object | Object defined for each event subscription depending on the event - it could be for example the ueID targeted by the subscription | optional | From 4d7ff14f2bf637ca4d1689858c95a0f90790c602 Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Tue, 13 Feb 2024 15:04:20 +0100 Subject: [PATCH 3/4] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index e7da7ddf..10835ec4 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1352,7 +1352,7 @@ Following Error code must be present: * case3: subscriber requests the `DELETE` operation for the subscription (if the subscription did not have a subscriptionExpireTime or before subscriptionExpireTime expires). * case4: subscription ends on operator request. -It could be useful to provide a mechanism to inform subscriber for all case. In this case, a specific event type could be used. +It could be useful to provide a mechanism to inform subscriber for all cases. In this case, a specific event type could be used. _Termination rules regarding subscriptionExpireTime & subscriptionMaxEvents usage_ * When client side providing a `subscriptionExpireTime` and/or `subscriptionMaxEvents` service side has to terminate the subscription without expecting a `DELETE` operation. From 386e3fe8e9fca8cf631731a61481223e2dc0c532 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Mon, 4 Mar 2024 09:13:51 +0100 Subject: [PATCH 4/4] Update documentation/API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 10835ec4..cbc2eaf2 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1357,7 +1357,7 @@ It could be useful to provide a mechanism to inform subscriber for all cases. In _Termination rules regarding subscriptionExpireTime & subscriptionMaxEvents usage_ * When client side providing a `subscriptionExpireTime` and/or `subscriptionMaxEvents` service side has to terminate the subscription without expecting a `DELETE` operation. * If both `subscriptionExpireTime` and `subscriptionMaxEvents` are provided, the subscription will end when the first one is reached. -* When the `subscriptionExpireTime` and `subscriptionMaxEvents` are not provided, client side has to trigger a `DELETE` operation to terminate it. +* When none `subscriptionExpireTime` and `subscriptionMaxEvents` are not provided, client side has to trigger a `DELETE` operation to terminate it. * It is perfectly valid for client side to trigger a DELETE operation before `subscriptionExpireTime` and/or `subscriptionMaxEvents` reached.