From c29aeccbf6d7d7810915d12d85766571efacfc37 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 11:27:38 +0200
Subject: [PATCH 01/45] Update event-subscription-template.yaml

Add  SUBSCRIPTION_UNPROCESSABLE in terminationReason enum for subscription ends event.
Solve https://github.com/camaraproject/Commonalities/issues/243
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index e28f39e8..a040a5a3 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -634,13 +634,14 @@ components:
         - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached
         - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached
         - SUBSCRIPTION_DELETED - Subscription was deleted by the requester
+        - SUBSCRIPTION_UNPROCESSABLE - Subscription cannot be processed due to some reason, e.g. because the specified area cannot be managed. Useful for asynchronous subscription creation.
       enum:
         - MAX_EVENTS_REACHED
         - NETWORK_TERMINATED
         - SUBSCRIPTION_EXPIRED
         - ACCESS_TOKEN_EXPIRED
         - SUBSCRIPTION_DELETED
-
+        - SUBSCRIPTION_UNPROCESSABLE
     HTTPSubscriptionRequest:
       allOf:
         - $ref: "#/components/schemas/SubscriptionRequest"

From 1a24c5321e7aba2b13ed260edbb7ed2ffcc002ec Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 11:34:22 +0200
Subject: [PATCH 02/45] Update API-design-guidelines.md

Explicit subscription-end termination reason usage.
Fix https://github.com/camaraproject/Commonalities/issues/243
---
 documentation/API-design-guidelines.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md
index cac51128..7d07d4b5 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1874,7 +1874,11 @@ 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 `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.
+#### subscription-ends event
+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, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml. 
+
 Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example, if a client request a `subscriptionMaxEvents` to 2, later, received second notification, then a third notification will be sent for "subscription-ends")
 
 #### Error definition for event notification

From fc41bbeebc022357ba35b777b016a6cdf1642d8e Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 11:44:17 +0200
Subject: [PATCH 03/45] Update API-design-guidelines.md

Update the "sink" property description
Fix https://github.com/camaraproject/Commonalities/issues/289
---
 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 7d07d4b5..bd53c5c7 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1677,7 +1677,7 @@ The following table provides `/subscriptions` attributes
 | name           | type               | attribute description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | cardinality                  |
 |----------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| 
 | protocol       | string             | Identifier of a delivery protocol. **Only** `HTTP` **is allowed for now**.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Mandatory                    |
-| sink           | string             | https callback address where the notification must be POST-ed                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory                    |
+| sink           | string             | The address to which events shall be delivered, using the HTTP protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory                    |
 | sinkCredential | object             | Sink credential provides authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. To protect the notification endpoint providing sinkCredential is RECOMMENDED.                                                                                                                                                                                                                                                                      | optional                     |
 | types          | string             | Type of event subscribed. This attribute **must** be present in the `POST` request. It is required by API project to provide an enum for this attribute. `type` must follow the format: `org.camaraproject.<api-name>.<api-version>.<event-name>` with the `api-version` with letter `v` and the major version like  ``org.camaraproject.device-roaming-subscriptions.v1.roaming-status`` - Note: An array of types could be passed **but as of now only one value MUST passed**. Use of multiple value will be open later at API level. | mandatory                    |
 | config         | object             | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like ``subscriptionExpireTime``, ``subscriptionMaxEvents`` or ``initialEvent``. See detail below.                                                                                                                                                                                                                                                                                      | mandatory                    |

From 8bd8ef59746c39e48e0f7b91e350d72e9aa9bf77 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 11:46:19 +0200
Subject: [PATCH 04/45] Update event-subscription-template.yaml

Update the "sink" property descriptionFix https://github.com/camaraproject/Commonalities/issues/289
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index a040a5a3..63c2aff1 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -294,7 +294,7 @@ components:
         sink:
           type: string
           format: url
-          description: The address to which events shall be delivered using the selected protocol.
+          description: The address to which events shall be delivered, using the HTTP protocol.
           example: "https://endpoint.example.com/sink"
         sinkCredential:
           $ref: "#/components/schemas/SinkCredential"

From 6030436736331977eba8a2151f2bb6405d796d93 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 12:32:24 +0200
Subject: [PATCH 05/45] Update API-design-guidelines.md

Add information for exiresAT + limitation to subscriptionMaxEvent and subscriptionExpireTime.
Fixes https://github.com/camaraproject/Commonalities/issues/303
---
 documentation/API-design-guidelines.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md
index bd53c5c7..1c4c5800 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1683,7 +1683,7 @@ The following table provides `/subscriptions` attributes
 | config         | object             | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like ``subscriptionExpireTime``, ``subscriptionMaxEvents`` or ``initialEvent``. See detail below.                                                                                                                                                                                                                                                                                      | mandatory                    |
 | id             | string             | Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory in server response |
 | 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 (optionally) by API server.                                                                                                                                                                                                                                                                                                                                                                                     | 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 (optionally) by API server. This attribute must be provided by the server if subscriptionExpireTime is provided in the request and server not able to handle it.                                                                                                                                                                                                                                                                                                                                                                                 | optional                     |
 | status         | string             | Current status of the subscription - Management of Subscription state engine is not mandatory for now. Note: not all statuses may be considered to be implemented. See below status table.                                                                                                                                                                                                                                                                                                                                               | optional                     |
 
 
@@ -1754,6 +1754,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.
+* CAMARA did not impose limitations for `subscriptionExpireTime` or `subscriptionMaxEvents` but API provider enforce limitations and have to document them.
 * If both `subscriptionExpireTime` and `subscriptionMaxEvents` are provided, the subscription will end when the first one is reached.
 * 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. 

From fef315bd8fb1655cb41804829725334f9b94955b Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 12:34:43 +0200
Subject: [PATCH 06/45] Update API-design-guidelines.md

fix line 1757
---
 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 1c4c5800..98156931 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1754,7 +1754,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.
-* CAMARA did not impose limitations for `subscriptionExpireTime` or `subscriptionMaxEvents` but API provider enforce limitations and have to document them.
+* CAMARA did not impose limitations for `subscriptionExpireTime` or `subscriptionMaxEvents` but API providers may enforce limitations and must document them accordinly.
 * If both `subscriptionExpireTime` and `subscriptionMaxEvents` are provided, the subscription will end when the first one is reached.
 * 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. 

From f05f4d3a2bf26503d203d9084d8961bd21d84fa8 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 10 Oct 2024 13:58:53 +0200
Subject: [PATCH 07/45] Update event-subscription-template.yaml

Proposal for https://github.com/camaraproject/Commonalities/issues/276

- POST /subscriptions response will have only `id`
- removed `sinkCredentials` from GET representation
---
 .../event-subscription-template.yaml           | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 63c2aff1..32deaa7d 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -98,7 +98,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Subscription"
+                $ref: "#/components/schemas/SubscriptionCreationResponse"
         "202":
           description: Request accepted to be processed. It applies for async creation process.
           headers:
@@ -294,7 +294,7 @@ components:
         sink:
           type: string
           format: url
-          description: The address to which events shall be delivered, using the HTTP protocol.
+          description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
         sinkCredential:
           $ref: "#/components/schemas/SinkCredential"
@@ -460,6 +460,15 @@ components:
         - org.camaraproject.api-name.v0.event-type
         - org.camaraproject.api-name.v0.subscription-ends
 
+    SubscriptionCreationResponse:
+      description: Response for the POST request
+      type: object
+      required:
+        - id
+      properties:
+        id:
+          $ref: '#/components/schemas/SubscriptionId'
+
     Subscription:
       description: Represents a event-type subscription.
       type: object
@@ -477,8 +486,6 @@ components:
           format: url
           description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
-        sinkCredential:
-          $ref: '#/components/schemas/SinkCredential'
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
@@ -634,14 +641,13 @@ components:
         - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached
         - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached
         - SUBSCRIPTION_DELETED - Subscription was deleted by the requester
-        - SUBSCRIPTION_UNPROCESSABLE - Subscription cannot be processed due to some reason, e.g. because the specified area cannot be managed. Useful for asynchronous subscription creation.
       enum:
         - MAX_EVENTS_REACHED
         - NETWORK_TERMINATED
         - SUBSCRIPTION_EXPIRED
         - ACCESS_TOKEN_EXPIRED
         - SUBSCRIPTION_DELETED
-        - SUBSCRIPTION_UNPROCESSABLE
+
     HTTPSubscriptionRequest:
       allOf:
         - $ref: "#/components/schemas/SubscriptionRequest"

From 51565779602518ddd83e9684b213338003bcace0 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 17 Oct 2024 20:38:03 +0200
Subject: [PATCH 08/45] Update event-subscription-template.yaml

Add a note on combined usage of initialEvent and subscriptionMaxEvents (https://github.com/camaraproject/Commonalities/issues/299)
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 32deaa7d..c8ffe8b6 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -4,6 +4,9 @@ info:
   description: |
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
+    Note on combined usage of initialEvent and subscriptionMaxEvents:
+    If an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
+
     Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document.
 
   license:

From aa621fd49f72456082a0edbedd6bcb3c814d0a87 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 17 Oct 2024 21:03:39 +0200
Subject: [PATCH 09/45] Update API-design-guidelines.md

Add part for:
- https://github.com/camaraproject/Commonalities/issues/304
- https://github.com/camaraproject/Commonalities/issues/299
- partial https://github.com/camaraproject/Commonalities/issues/295
---
 documentation/API-design-guidelines.md | 63 ++++++++++++++++++++------
 1 file changed, 49 insertions(+), 14 deletions(-)

diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md
index 98156931..797d59f8 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -13,7 +13,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
     - [2.2 API First](#22-api-first)
     - [2.3 Interface standardization. Standardization fora.](#23-interface-standardization-standardization-fora)
     - [2.4 Information Representation Standard](#24-information-representation-standard)
-  - [2.5 Reduce telco-specific terminology in API definitions](#25-reduce-telco-specific-terminology-in-api-definitions)
+    - [2.5 Reduce telco-specific terminology in API definitions](#25-reduce-telco-specific-terminology-in-api-definitions)
   - [3. API Definition](#3-api-definition)
     - [3.1 API REST](#31-api-rest)
       - [POST or GET for transferring sensitive or complex data](#post-or-get-for-transferring-sensitive-or-complex-data)
@@ -66,16 +66,21 @@ This document captures guidelines for the API design in CAMARA project. These gu
           - [Examples](#examples)
         - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions)
         - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara)
+    - [11.7 API access restriction (Based on token \& client Id)](#117-api-access-restriction-based-on-token--client-id)
   - [12. Subscription, Notification \& Event](#12-subscription-notification--event)
     - [12.1 Subscription](#121-subscription)
       - [Instance-based (implicit) subscription](#instance-based-implicit-subscription)
         - [Instance-based (implicit) subscription example](#instance-based-implicit-subscription-example)
       - [Resource-based (explicit) subscription](#resource-based-explicit-subscription)
+        - [Operations](#operations)
+        - [Rules for subscriptions data minimization](#rules-for-subscriptions-data-minimization)
+        - [Subscriptions data model](#subscriptions-data-model)
         - [Error definition for resource-based (explicit) subscription](#error-definition-for-resource-based-explicit-subscription)
         - [Termination for resource-based (explicit) subscription](#termination-for-resource-based-explicit-subscription)
         - [Resource-based (explicit) example](#resource-based-explicit-example)
     - [12.2 Event notification](#122-event-notification)
       - [Event notification definition](#event-notification-definition)
+      - [subscription-ends event](#subscription-ends-event)
       - [Error definition for event notification](#error-definition-for-event-notification)
       - [Correlation Management](#correlation-management)
       - [Security Considerations](#security-considerations)
@@ -551,23 +556,23 @@ API versions use a numbering scheme in the format: `x.y.z`
 
 ### 5.1 API version (OAS info object)
 
-The API version is defined in the `version` field (in the `info` object) of the OAS definition file of an API. 
+The API version is defined in the `version` field (in the `info` object) of the OAS definition file of an API. 
 
 ```yaml
 info:
   title: Number Verification
   description: text describing the API
-  version: 2.2.0  
+  version: 2.2.0  
   #...
 ```
 
-In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows:
+In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows:
 
-1. The MAJOR version when an incompatible / breaking API change is introduced
-2. The MINOR version when functionality is added that is backwards compatible
-3. The PATCH version when backward compatible bugs are fixed
+1. The MAJOR version when an incompatible / breaking API change is introduced
+2. The MINOR version when functionality is added that is backwards compatible
+3. The PATCH version when backward compatible bugs are fixed
 
-For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the CAMARA wiki. 
+For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the CAMARA wiki. 
 
 It is recommended to avoid breaking backward compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below.
 
@@ -579,7 +584,7 @@ The API version in the `url` field only includes the "x" (MAJOR version) number
 
 ```yaml
 servers:
-    url: {apiRoot}/qod/v2
+    url: {apiRoot}/qod/v2
 ```
 
 ---
@@ -590,7 +595,7 @@ IMPORTANT: CAMARA public APIs with x=0 (`v0.x.y`) MUST use both the MAJOR and th
 
 ```yaml
 servers:
-    url: {apiRoot}/number-verification/v0.3
+    url: {apiRoot}/number-verification/v0.3
 ```
 
 This allows for both test and commercial usage of initial API versions as they are evolving rapidly, e.g. `/qod/v0.10alpha1`, `/qod/v0.10rc1`, or `/qod/v0.10`. However, it should be acknowledged that any initial API version may change.
@@ -604,7 +609,7 @@ Overall, an API can have any of the following versions:
 * work-in-progress (`wip`) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers.
 * alpha (`x.y.z-alpha.m`) API versions (with extensions) for CAMARA internal API rapid development purposes
 * release-candidate (`x.y.z-rc.n`) API versions (with extensions) for CAMARA internal API release bug fixing purposes
-* public (`x.y.z`) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states (used in release management): 
+* public (`x.y.z`) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states (used in release management): 
   * initial - indicating that the API is still not fully stable (x=0)
   * stable - indicate that the API has reached a certain level of maturity (x>0)
 
@@ -614,7 +619,7 @@ The following table gives the values of the API version (Info object) and the AP
 |-------------------|:-------------:|:--------------------------------:|:-------------------------------:|:---------------------------:|
 | work-in-progress  |      wip      |               vwip               |              vwip               |             No              |
 | alpha             | x.y.z-alpha.m |            v0.yalpham            |            vxalpham             | Yes (internal pre-release)  |
-| release-candidate |   x.y.z-rc.n  |             v0.yrcn              |              vxrcn              | Yes (internal pre-release)  |
+| release-candidate |   x.y.z-rc.n  |             v0.yrcn              |              vxrcn              | Yes (internal pre-release)  |
 | public            |     x.y.z     |               v0.y               |               vx                |             Yes             |
 
 Precedence examples:
@@ -666,7 +671,7 @@ Compatibility management:
 To ensure this compatibility, the following guidelines must be applied.
 
 **As API provider**:
-- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later MAJOR change (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality)
+- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later MAJOR change (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality)
 - If possible, do the same for attributes
 - New fields should always be added as optional.
 - Postel's Law: “<em>Be conservative in what you do, be liberal in what you accept from others</em>”. When you have input fields that need to be removed, mark them as unused, so they can be ignored. 
@@ -1568,6 +1573,22 @@ The decision on the API-level scopes was made within the [Identity and Consent M
 The scopes will always be those defined in the API Specs YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API Spec YAML file and agreed in the corresponding API subproject. 
 
 
+### 11.7 API access restriction (Based on token & client Id)
+
+In some CAMARA API we have functions to create resource (via POST) and then later query them via id and/or list (with GET) or delete them (via DELETE). For example we have sessions, payments, subscriptions, etc..
+
+For the GET and DELETE operations we must restrict the resource(s) targeted based on the request. Basically we consider 2 filters:
+* API client (aka ClientId)
+* access token
+
+| Operation |  3-legged access token is used | 2-legged access token is used |
+|-----------|--------------------------------|-------------------------------|
+| GET/{id} | -The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token.  | - The resource queried must must have been created by the same API client given in the access token. |
+| GET/| -Return all resource(s) created by the API consumer that are associated with both the end user identified by the token and the same API client given in the access token.| Return all resource(s) created by the same API client given in the access token.|
+| DELETE/{id} | -The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token  | - The resource to be deleted must must have been created by the same API client given in the access token. |
+
+
+
 ## 12. Subscription, Notification & Event
 
 To provide event-based interaction, CAMARA API could provide capabilities for subscription & notification management.
@@ -1645,6 +1666,7 @@ CAMARA subscription model leverages **[CloudEvents](https://cloudevents.io/)** a
 
 To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. It is mandatory to append the keyword "subscriptions" at the end of the API name. For e.g. device-roaming-subscriptions.yaml
 
+##### Operations
 Four operations must be defined:
 
 | operation | path                              | description                                                                                                                                                                                            |
@@ -1672,13 +1694,22 @@ The rationale for using this alternate pattern should be explicitly provided
 (e.g. the notification source for each of the supported events may be completely different,
 in which case, separating the implementations is beneficial). 
 
+##### Rules for subscriptions data minimization 
+
+These rules apply for subscription with device identifier
+- If 3-legged access token is used, the POST and GET responses must not provide any device identifier.
+- If 2-legged access token is used, the presence of a device identifier in the response is mandatory and should the same identifier type than the one provided in the request.
+
+
+
+##### Subscriptions data model
 The following table provides `/subscriptions` attributes
 
 | name           | type               | attribute description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | cardinality                  |
 |----------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------| 
 | protocol       | string             | Identifier of a delivery protocol. **Only** `HTTP` **is allowed for now**.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Mandatory                    |
 | sink           | string             | The address to which events shall be delivered, using the HTTP protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory                    |
-| sinkCredential | object             | Sink credential provides authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. To protect the notification endpoint providing sinkCredential is RECOMMENDED.                                                                                                                                                                                                                                                                      | optional                     |
+| sinkCredential | object             | Sink credential provides authorization information necessary to enable delivery of events to a target. In order to be updated in future this object is polymorphic. See detail below. To protect the notification endpoint providing sinkCredential is RECOMMENDED. <br> The sinkCredential must **not** be present in `POST` and `GET` responses.                                                                                                                                                                                                                                                                    | optional                     |
 | types          | string             | Type of event subscribed. This attribute **must** be present in the `POST` request. It is required by API project to provide an enum for this attribute. `type` must follow the format: `org.camaraproject.<api-name>.<api-version>.<event-name>` with the `api-version` with letter `v` and the major version like  ``org.camaraproject.device-roaming-subscriptions.v1.roaming-status`` - Note: An array of types could be passed **but as of now only one value MUST passed**. Use of multiple value will be open later at API level. | mandatory                    |
 | config         | object             | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like ``subscriptionExpireTime``, ``subscriptionMaxEvents`` or ``initialEvent``. See detail below.                                                                                                                                                                                                                                                                                      | mandatory                    |
 | id             | string             | Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory in server response |
@@ -1715,6 +1746,10 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 | initialEvent           | boolean            | Set to true by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. Up to API project decision to keep it. | optional    |
 
 
+Note on combined usage of initialEvent and subscriptionMaxEvents: 
+Unless explicitly decided otherwise by the API WG,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
+It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
+
 Subscription status value table:
 
 Managing subscription is a draft feature, and it is not mandatory for now. An API project could decide to use/not use it. A list of status is provided for global consistency.

From 8b8dab891e54c717550ccc367fab276bfbc398fe Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 17 Oct 2024 21:06:52 +0200
Subject: [PATCH 10/45] Update API-design-guidelines.md

Fixe line 1580
---
 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 797d59f8..b99d1c06 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1577,7 +1577,7 @@ The scopes will always be those defined in the API Specs YAML files. Thus, a sco
 
 In some CAMARA API we have functions to create resource (via POST) and then later query them via id and/or list (with GET) or delete them (via DELETE). For example we have sessions, payments, subscriptions, etc..
 
-For the GET and DELETE operations we must restrict the resource(s) targeted based on the request. Basically we consider 2 filters:
+For the GET and DELETE operations we must restrict the resource(s) targeted depending on the information provided in the request. Basically we consider 2 filters:
 * API client (aka ClientId)
 * access token
 

From e1c6ca82f0a1c742ea181036416d781cfb06b171 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:56:53 +0200
Subject: [PATCH 11/45] Update
 artifacts/camara-cloudevents/event-subscription-template.yaml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index c8ffe8b6..eaf463b1 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -4,7 +4,7 @@ info:
   description: |
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
-    Note on combined usage of initialEvent and subscriptionMaxEvents:
+    Note on combined usage of `initialEvent` and `subscriptionMaxEvents`:
     If an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
 
     Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document.

From 28268557ce6409a5e10af12aac21065ddc90873b Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:57:06 +0200
Subject: [PATCH 12/45] Update
 artifacts/camara-cloudevents/event-subscription-template.yaml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index eaf463b1..349f8b8c 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -5,7 +5,7 @@ info:
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
     Note on combined usage of `initialEvent` and `subscriptionMaxEvents`:
-    If an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
+    If an event is triggered following `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents` (if provided).
 
     Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document.
 

From f488c6d0ac85aac5e38795170a6087c822bd27df Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:57:34 +0200
Subject: [PATCH 13/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 b99d1c06..cddf0ab3 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1575,7 +1575,7 @@ The scopes will always be those defined in the API Specs YAML files. Thus, a sco
 
 ### 11.7 API access restriction (Based on token & client Id)
 
-In some CAMARA API we have functions to create resource (via POST) and then later query them via id and/or list (with GET) or delete them (via DELETE). For example we have sessions, payments, subscriptions, etc..
+In some CAMARA APIs there are functions to create resource (via POST) and then later query them via id and/or list (with GET) or delete them (via DELETE). For example we have sessions, payments, subscriptions, etc..
 
 For the GET and DELETE operations we must restrict the resource(s) targeted depending on the information provided in the request. Basically we consider 2 filters:
 * API client (aka ClientId)

From b00788b90b1bb688f740b722f8f7f80693f0be18 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:57:47 +0200
Subject: [PATCH 14/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 cddf0ab3..6842ce3e 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1583,7 +1583,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 
 | Operation |  3-legged access token is used | 2-legged access token is used |
 |-----------|--------------------------------|-------------------------------|
-| GET/{id} | -The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token.  | - The resource queried must must have been created by the same API client given in the access token. |
+| GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must must have been created by the same API client given in the access token. |
 | GET/| -Return all resource(s) created by the API consumer that are associated with both the end user identified by the token and the same API client given in the access token.| Return all resource(s) created by the same API client given in the access token.|
 | DELETE/{id} | -The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token  | - The resource to be deleted must must have been created by the same API client given in the access token. |
 

From 20343b3121562ab3415bb319ba90407491fc9881 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:57:56 +0200
Subject: [PATCH 15/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 6842ce3e..7b726e01 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1584,7 +1584,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 | Operation |  3-legged access token is used | 2-legged access token is used |
 |-----------|--------------------------------|-------------------------------|
 | GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must must have been created by the same API client given in the access token. |
-| GET/| -Return all resource(s) created by the API consumer that are associated with both the end user identified by the token and the same API client given in the access token.| Return all resource(s) created by the same API client given in the access token.|
+| GET/ | - Return all resource(s) created by the API consumer that are associated with both the end user identified by the access token and the same API client given in the access token. | - Return all resource(s) created by the same API client given in the access token. |
 | DELETE/{id} | -The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token  | - The resource to be deleted must must have been created by the same API client given in the access token. |
 
 

From cd24b80e9746cbdc35c076f260a8a8bbd0914c60 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:58:09 +0200
Subject: [PATCH 16/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 7b726e01..0248116a 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1698,7 +1698,7 @@ in which case, separating the implementations is beneficial).
 
 These rules apply for subscription with device identifier
 - If 3-legged access token is used, the POST and GET responses must not provide any device identifier.
-- If 2-legged access token is used, the presence of a device identifier in the response is mandatory and should the same identifier type than the one provided in the request.
+- If 2-legged access token is used, the presence of a device identifier in the response is mandatory and should be the same identifier type than the one provided in the request.
 
 
 

From 53c052b59ac164a49962b2493532146a1144ae4c Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:58:21 +0200
Subject: [PATCH 17/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 0248116a..e523c928 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1714,7 +1714,7 @@ The following table provides `/subscriptions` attributes
 | config         | object             | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like ``subscriptionExpireTime``, ``subscriptionMaxEvents`` or ``initialEvent``. See detail below.                                                                                                                                                                                                                                                                                      | mandatory                    |
 | id             | string             | Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server                                                                                                                                                                                                                                                                                                                                                                                                            | mandatory in server response |
 | 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 (optionally) by API server. This attribute must be provided by the server if subscriptionExpireTime is provided in the request and server not able to handle it.                                                                                                                                                                                                                                                                                                                                                                                 | 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 (optionally) by API server. This attribute must be provided by the server if subscriptionExpireTime is provided in the request and server is not able to handle it.                                                                                                                                                                                                                                                                                                                                                                                 | optional                     |
 | status         | string             | Current status of the subscription - Management of Subscription state engine is not mandatory for now. Note: not all statuses may be considered to be implemented. See below status table.                                                                                                                                                                                                                                                                                                                                               | optional                     |
 
 

From 9a61691b01d7a2454f33daa51ed1a8081500309a Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:58:32 +0200
Subject: [PATCH 18/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 e523c928..b9a2da7c 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1585,7 +1585,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 |-----------|--------------------------------|-------------------------------|
 | GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must must have been created by the same API client given in the access token. |
 | GET/ | - Return all resource(s) created by the API consumer that are associated with both the end user identified by the access token and the same API client given in the access token. | - Return all resource(s) created by the same API client given in the access token. |
-| DELETE/{id} | -The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token  | - The resource to be deleted must must have been created by the same API client given in the access token. |
+| DELETE/{id} | - The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token. | - The resource to be deleted must must have been created by the same API client given in the access token. |
 
 
 

From cdc1ecddb391c16c7a81f92a370267e291e9f2b2 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 14:58:45 +0200
Subject: [PATCH 19/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 b9a2da7c..de1370c5 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1746,7 +1746,7 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 | initialEvent           | boolean            | Set to true by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. Up to API project decision to keep it. | optional    |
 
 
-Note on combined usage of initialEvent and subscriptionMaxEvents: 
+**Note** on combined usage of initialEvent and subscriptionMaxEvents: 
 Unless explicitly decided otherwise by the API WG,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
 It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
 

From d0b4fc32e6b9ba31a9988399440f38ed67385f9f Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 15:00:20 +0200
Subject: [PATCH 20/45] Update API-design-guidelines.md

Highlight Subscription status value table
---
 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 de1370c5..840021b8 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1750,7 +1750,7 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 Unless explicitly decided otherwise by the API WG,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
 It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
 
-Subscription status value table:
+**Subscription status value table**:
 
 Managing subscription is a draft feature, and it is not mandatory for now. An API project could decide to use/not use it. A list of status is provided for global consistency.
 

From e7d54447b0a474c3c29e2ba8d89466358f4e0e8d Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 15:03:53 +0200
Subject: [PATCH 21/45] Update API-design-guidelines.md

Add link to artifacts/camara-cloudevents/event-subscription-template.yaml
---
 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 840021b8..ac9b3e34 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1913,7 +1913,7 @@ Note: For operational and troubleshooting purposes it is relevant to accommodate
 #### subscription-ends event
 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, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml. 
+It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notification prematurely, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml (available here: artifacts/camara-cloudevents/event-subscription-template.yaml). 
 
 Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example, if a client request a `subscriptionMaxEvents` to 2, later, received second notification, then a third notification will be sent for "subscription-ends")
 

From 5d007516e701a624aec4f10a4216089b842144b7 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 18 Oct 2024 15:10:07 +0200
Subject: [PATCH 22/45] Update API-design-guidelines.md

Fix link
---
 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 ac9b3e34..6d562340 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1913,7 +1913,7 @@ Note: For operational and troubleshooting purposes it is relevant to accommodate
 #### subscription-ends event
 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, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml (available here: artifacts/camara-cloudevents/event-subscription-template.yaml). 
+It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notification prematurely, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml (see in [Commonalities/artifacts/camara-cloudevents](/artifacts/camara-cloudevents) directory ``event-subscription-template.yaml``). 
 
 Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example, if a client request a `subscriptionMaxEvents` to 2, later, received second notification, then a third notification will be sent for "subscription-ends")
 

From ee2a79f061df938f1e09cb361806fb6e6df4013c Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 22 Oct 2024 08:41:53 +0200
Subject: [PATCH 23/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 6d562340..0211c337 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1583,7 +1583,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 
 | Operation |  3-legged access token is used | 2-legged access token is used |
 |-----------|--------------------------------|-------------------------------|
-| GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must must have been created by the same API client given in the access token. |
+| GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must have been created by the same API client given in the access token. |
 | GET/ | - Return all resource(s) created by the API consumer that are associated with both the end user identified by the access token and the same API client given in the access token. | - Return all resource(s) created by the same API client given in the access token. |
 | DELETE/{id} | - The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token. | - The resource to be deleted must must have been created by the same API client given in the access token. |
 

From 7db3e2c7b3de74b8a8dd344eeb6af5d3bb7d94c0 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 22 Oct 2024 08:42:02 +0200
Subject: [PATCH 24/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 0211c337..6a6a0a07 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1585,7 +1585,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 |-----------|--------------------------------|-------------------------------|
 | GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must have been created by the same API client given in the access token. |
 | GET/ | - Return all resource(s) created by the API consumer that are associated with both the end user identified by the access token and the same API client given in the access token. | - Return all resource(s) created by the same API client given in the access token. |
-| DELETE/{id} | - The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must must have been created by the same API client given in the access token. | - The resource to be deleted must must have been created by the same API client given in the access token. |
+| DELETE/{id} | - The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must have been created by the same API client given in the access token. | - The resource to be deleted must have been created by the same API client given in the access token. |
 
 
 

From 0acd0af00580ff1bd5e6b4dbba0c4f691f84846e Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 22 Oct 2024 08:42:29 +0200
Subject: [PATCH 25/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 6a6a0a07..a427416d 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1789,7 +1789,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.
-* CAMARA did not impose limitations for `subscriptionExpireTime` or `subscriptionMaxEvents` but API providers may enforce limitations and must document them accordinly.
+* CAMARA does not impose limitations for `subscriptionExpireTime` or `subscriptionMaxEvents` but API providers may enforce limitations and must document them accordingly.
 * If both `subscriptionExpireTime` and `subscriptionMaxEvents` are provided, the subscription will end when the first one is reached.
 * 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. 

From 93ee9ae452d3de6f75d9fc6bb852f75ddf8dbd47 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 22 Oct 2024 18:50:09 +0200
Subject: [PATCH 26/45] Update API-design-guidelines.md

Adding Application of data minimization design must be considered by the API working group for event structure definition.
---
 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 a427416d..1a1a618f 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1700,7 +1700,7 @@ These rules apply for subscription with device identifier
 - If 3-legged access token is used, the POST and GET responses must not provide any device identifier.
 - If 2-legged access token is used, the presence of a device identifier in the response is mandatory and should be the same identifier type than the one provided in the request.
 
-
+Application of data minimization design must be considered by the API working group for event structure definition.
 
 ##### Subscriptions data model
 The following table provides `/subscriptions` attributes

From 754f3fd55c95243c4912ff3275ae936371ea34bb Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 29 Oct 2024 09:37:57 +0100
Subject: [PATCH 27/45] Update event-subscription-template.yaml

Solve #326 by updating servers field
---
 .../camara-cloudevents/event-subscription-template.yaml  | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 349f8b8c..c5e4a3d3 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -19,14 +19,13 @@ externalDocs:
   description: Product documentation at CAMARA
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/{apiName}/v0.1"
+  - url: "{apiRoot}/api-name/vx.y"
+  # api-name and version should valued accordingly to the API
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root
-      apiName:
-        default: camaraAPI
-        description: apiName will be replaced in WG by its value and not modelled as a variable
+        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
+
 tags:
   - name: <apiName> Subscription
     description: Operations to manage event subscriptions on event-type event

From c9c187e83fc5ca66e590d149f00e0ed7f4ec01a6 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 29 Oct 2024 09:42:37 +0100
Subject: [PATCH 28/45] Update event-subscription-template.yaml

Remove error code 415

request: https://github.com/camaraproject/Commonalities/issues/321#issuecomment-2429158445
---
 .../event-subscription-template.yaml           | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index c5e4a3d3..952e28e8 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -118,8 +118,6 @@ paths:
           $ref: "#/components/responses/SubscriptionPermissionDenied403"
         "409":
           $ref: "#/components/responses/Generic409"
-        "415":
-          $ref: "#/components/responses/Generic415"
         "422":
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
@@ -974,22 +972,6 @@ components:
                 status: 410
                 code: GONE
                 message: Access to the target resource is no longer available.
-    Generic415:
-      description: Unsupported Media Type
-      headers:
-        X-Correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
-              description: Payload format of the request is in an unsupported format by the Server. Should not happen
-              value:
-                status: 415
-                code: UNSUPPORTED_MEDIA_TYPE
-                message: The server refuses to accept the request because the payload format is in an unsupported format
     CreateSubscriptionUnprocessableEntity422:
       description: Unprocessable Entity
       headers:

From cc80891955a4ebe7d569fd996e380149da2b816b Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 29 Oct 2024 09:53:23 +0100
Subject: [PATCH 29/45] Update event-subscription-template.yaml

Remove 403_INVALID_TOKEN_CONTEXT
adding GENERIC_422_UNNECESSARY_IDENTIFIER
adding GENERIC_422_MISSING_IDENTIFIER
---
 .../event-subscription-template.yaml           | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 952e28e8..7ebb8f0e 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -907,12 +907,6 @@ components:
                 status: 403
                 code: PERMISSION_DENIED
                 message: Client does not have sufficient permissions to perform this action.
-            GENERIC_403_INVALID_TOKEN_CONTEXT:
-              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
-              value:
-                status: 403
-                code: INVALID_TOKEN_CONTEXT
-                message: "{{field}} is not consistent with access token."
             GENERIC_403_SUBSCRIPTION_MISMATCH:
               value:
                 status: 403
@@ -999,6 +993,18 @@ components:
                 status: 422
                 code: DEVICE_NOT_APPLICABLE
                 message: The service is not available for the provided device.
+            GENERIC_422_UNNECESSARY_IDENTIFIER:
+              description: An explicit identifier is provided when an API subject has already been identified from the access token
+              value:
+                status: 422
+                code: UNNECESSARY_IDENTIFIER
+                message: The device is already identified by the access
+            GENERIC_422_MISSING_IDENTIFIER:
+              description: An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token
+              value:
+                status: 422
+                code: MISSING_IDENTIFIER
+                message: The device cannot be identified
     Generic429:
       description: Too Many Requests
       headers:

From e61feafae2e3f757749358ac0475712792ed46bf Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 29 Oct 2024 12:37:25 +0100
Subject: [PATCH 30/45] Update
 artifacts/camara-cloudevents/event-subscription-template.yaml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 7ebb8f0e..0818cd90 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -998,7 +998,7 @@ components:
               value:
                 status: 422
                 code: UNNECESSARY_IDENTIFIER
-                message: The device is already identified by the access
+                message: The device is already identified by the access token
             GENERIC_422_MISSING_IDENTIFIER:
               description: An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token
               value:

From abf4e753a3ffa596b5d9f5ac677b78449c89faaf Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Wed, 30 Oct 2024 15:39:32 +0100
Subject: [PATCH 31/45] Update event-subscription-template.yaml

Remove error code 500 & 503
---
 .../event-subscription-template.yaml          | 53 -------------------
 1 file changed, 53 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 0818cd90..5e0694f9 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -83,14 +83,9 @@ paths:
                   $ref: "#/components/responses/Generic410"
                 "429":
                   $ref: "#/components/responses/Generic429"
-                "500":
-                  $ref: "#/components/responses/Generic500"
-                "503":
-                  $ref: "#/components/responses/Generic503"
               security:
                 - {}
                 - notificationsBearerAuth: []
-
       responses:
         "201":
           description: Created
@@ -122,10 +117,6 @@ paths:
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
           $ref: "#/components/responses/Generic429"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     get:
       tags:
         - <apiName> Subscription
@@ -156,10 +147,6 @@ paths:
           $ref: "#/components/responses/Generic401"
         "403":
           $ref: "#/components/responses/Generic403"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
   /subscriptions/{subscriptionId}:
     get:
       tags:
@@ -191,10 +178,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     delete:
       tags:
         - <apiName> Subscription
@@ -230,10 +213,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
 components:
   securitySchemes:
     openId:
@@ -1027,38 +1006,6 @@ components:
                 status: 429
                 code: TOO_MANY_REQUESTS
                 message: Either out of resource quota or reaching rate limiting.
-    Generic500:
-      description: Server error
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_500_INTERNAL:
-              description: Problem in Server side. Regular Server Exception
-              value:
-                status: 500
-                code: INTERNAL
-                message: Unknown server error. Typically a server bug.
-    Generic503:
-      description: Service unavailable. Typically the server is down.
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_503_UNAVAILABLE:
-              description: Service is not available. Temporary situation usually related to maintenance process in the server side
-              value:
-                status: 503
-                code: UNAVAILABLE
-                message: Service Unavailable.
     SubscriptionIdRequired:
       description: Problem with the client request
       headers:

From c9c344eae6442fc58a0c66f7e939be0b18565bcf Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Wed, 6 Nov 2024 13:40:05 +0100
Subject: [PATCH 32/45] Update event-subscription-template.yaml

Add 2 exemples of event type
Add a note for event type name convention
Aligned event type example name
Event type in subscription managed in an enumeration
---
 .../event-subscription-template.yaml          | 148 +++++++++++++-----
 1 file changed, 111 insertions(+), 37 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 5e0694f9..8fc31001 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -4,10 +4,9 @@ info:
   description: |
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
-    Note on combined usage of `initialEvent` and `subscriptionMaxEvents`:
-    If an event is triggered following `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents` (if provided).
+    Note on event name convention: the event type name MUST follow: ``org.camaraproject.<api-name>.<api-version>.<event-name>`` 
 
-    Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document.
+    Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type1:grant-level` must be replaced accordingly to the format defined in the guideline document.
 
   license:
     name: Apache 2.0
@@ -19,13 +18,14 @@ externalDocs:
   description: Product documentation at CAMARA
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/api-name/vx.y"
-  # api-name and version should valued accordingly to the API
+  - url: "{apiRoot}/{apiName}/v0.1"
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
-
+        description: API root
+      apiName:
+        default: camaraAPI
+        description: apiName will be replaced in WG by its value and not modelled as a variable
 tags:
   - name: <apiName> Subscription
     description: Operations to manage event subscriptions on event-type event
@@ -42,7 +42,8 @@ paths:
         - $ref: "#/components/parameters/x-correlator"
       security:
         - openId:
-            - api-name:event-type:grant-level
+            - api-name:event-type1:grant-level
+            - api-name:event-type2:grant-level
       requestBody:
         content:
           application/json:
@@ -83,9 +84,14 @@ paths:
                   $ref: "#/components/responses/Generic410"
                 "429":
                   $ref: "#/components/responses/Generic429"
+                "500":
+                  $ref: "#/components/responses/Generic500"
+                "503":
+                  $ref: "#/components/responses/Generic503"
               security:
                 - {}
                 - notificationsBearerAuth: []
+
       responses:
         "201":
           description: Created
@@ -95,7 +101,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SubscriptionCreationResponse"
+                $ref: "#/components/schemas/Subscription"
         "202":
           description: Request accepted to be processed. It applies for async creation process.
           headers:
@@ -113,10 +119,16 @@ paths:
           $ref: "#/components/responses/SubscriptionPermissionDenied403"
         "409":
           $ref: "#/components/responses/Generic409"
+        "415":
+          $ref: "#/components/responses/Generic415"
         "422":
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
           $ref: "#/components/responses/Generic429"
+        "500":
+          $ref: "#/components/responses/Generic500"
+        "503":
+          $ref: "#/components/responses/Generic503"
     get:
       tags:
         - <apiName> Subscription
@@ -147,6 +159,10 @@ paths:
           $ref: "#/components/responses/Generic401"
         "403":
           $ref: "#/components/responses/Generic403"
+        "500":
+          $ref: "#/components/responses/Generic500"
+        "503":
+          $ref: "#/components/responses/Generic503"
   /subscriptions/{subscriptionId}:
     get:
       tags:
@@ -178,6 +194,10 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
+        "500":
+          $ref: "#/components/responses/Generic500"
+        "503":
+          $ref: "#/components/responses/Generic503"
     delete:
       tags:
         - <apiName> Subscription
@@ -213,6 +233,10 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
+        "500":
+          $ref: "#/components/responses/Generic500"
+        "503":
+          $ref: "#/components/responses/Generic503"
 components:
   securitySchemes:
     openId:
@@ -280,13 +304,12 @@ components:
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
-            Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
-             at API project level.
+            Note: for the current Commonalities version (v0.5) only one event type per subscription is allowed, yet in the following releases use of array of event types SHALL be specified without changing this definition.
           type: array
           minItems: 1
           maxItems: 1
           items:
-            type: string
+            $ref: "#/components/schemas/SubscriptionEventType"
         config:
           $ref: "#/components/schemas/Config"
       discriminator:
@@ -432,21 +455,21 @@ components:
     EventTypeNotification:
       type: string
       description: |
-        event-type - Event triggered when an event-type event occurred
+        event-type - Event triggered when an event-type event occurred. Several event-type could be defined.
 
         subscription-ends: Event triggered when the subscription ends
       enum:
-        - org.camaraproject.api-name.v0.event-type
+        - org.camaraproject.api-name.v0.event-type1
+        - org.camaraproject.api-name.v0.event-type2
         - org.camaraproject.api-name.v0.subscription-ends
 
-    SubscriptionCreationResponse:
-      description: Response for the POST request
-      type: object
-      required:
-        - id
-      properties:
-        id:
-          $ref: '#/components/schemas/SubscriptionId'
+    SubscriptionEventType:
+      type: string
+      description: |
+        event-type that could be subscribed through this subscription. Several event-type could be defined.
+      enum:
+        - org.camaraproject.api-name.v0.event-type1
+        - org.camaraproject.api-name.v0.event-type2
 
     Subscription:
       description: Represents a event-type subscription.
@@ -465,6 +488,8 @@ components:
           format: url
           description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
+        sinkCredential:
+          $ref: '#/components/schemas/SinkCredential'
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
@@ -558,7 +583,8 @@ components:
       discriminator:
         propertyName: "type"
         mapping:
-          org.camaraproject.api-name.v0.event-type: "#/components/schemas/Event-typeEvent"
+          org.camaraproject.api-name.v0.event-type1: "#/components/schemas/EventApiSpecific1"
+          org.camaraproject.api-name.v0.event-type2: "#/components/schemas/EventApiSpecific2"
           org.camaraproject.api-name.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds"
 
     Source:
@@ -583,8 +609,14 @@ components:
       description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
       example: "2018-04-05T17:31:00Z"
 
-    Event-typeEvent:
-      description: event structure for event-type event
+    EventApiSpecific1:
+      description: event structure for event-type event 1
+      allOf:
+        - $ref: "#/components/schemas/CloudEvent"
+        - type: object
+
+    EventApiSpecific2:
+      description: event structure for event-type event 2
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
@@ -886,6 +918,12 @@ components:
                 status: 403
                 code: PERMISSION_DENIED
                 message: Client does not have sufficient permissions to perform this action.
+            GENERIC_403_INVALID_TOKEN_CONTEXT:
+              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                message: "{{field}} is not consistent with access token."
             GENERIC_403_SUBSCRIPTION_MISMATCH:
               value:
                 status: 403
@@ -945,6 +983,22 @@ components:
                 status: 410
                 code: GONE
                 message: Access to the target resource is no longer available.
+    Generic415:
+      description: Unsupported Media Type
+      headers:
+        X-Correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
+              description: Payload format of the request is in an unsupported format by the Server. Should not happen
+              value:
+                status: 415
+                code: UNSUPPORTED_MEDIA_TYPE
+                message: The server refuses to accept the request because the payload format is in an unsupported format
     CreateSubscriptionUnprocessableEntity422:
       description: Unprocessable Entity
       headers:
@@ -972,18 +1026,6 @@ components:
                 status: 422
                 code: DEVICE_NOT_APPLICABLE
                 message: The service is not available for the provided device.
-            GENERIC_422_UNNECESSARY_IDENTIFIER:
-              description: An explicit identifier is provided when an API subject has already been identified from the access token
-              value:
-                status: 422
-                code: UNNECESSARY_IDENTIFIER
-                message: The device is already identified by the access token
-            GENERIC_422_MISSING_IDENTIFIER:
-              description: An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token
-              value:
-                status: 422
-                code: MISSING_IDENTIFIER
-                message: The device cannot be identified
     Generic429:
       description: Too Many Requests
       headers:
@@ -1006,6 +1048,38 @@ components:
                 status: 429
                 code: TOO_MANY_REQUESTS
                 message: Either out of resource quota or reaching rate limiting.
+    Generic500:
+      description: Server error
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_500_INTERNAL:
+              description: Problem in Server side. Regular Server Exception
+              value:
+                status: 500
+                code: INTERNAL
+                message: Unknown server error. Typically a server bug.
+    Generic503:
+      description: Service unavailable. Typically the server is down.
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_503_UNAVAILABLE:
+              description: Service is not available. Temporary situation usually related to maintenance process in the server side
+              value:
+                status: 503
+                code: UNAVAILABLE
+                message: Service Unavailable.
     SubscriptionIdRequired:
       description: Problem with the client request
       headers:

From b435e828f5ac9a81f615b741515938725209f66d Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Tue, 12 Nov 2024 20:33:05 +0100
Subject: [PATCH 33/45] Update event-subscription-template.yaml

Removed code 415, 500 & 503
---
 .../event-subscription-template.yaml          | 70 -------------------
 1 file changed, 70 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 8fc31001..6ad6866a 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -84,10 +84,6 @@ paths:
                   $ref: "#/components/responses/Generic410"
                 "429":
                   $ref: "#/components/responses/Generic429"
-                "500":
-                  $ref: "#/components/responses/Generic500"
-                "503":
-                  $ref: "#/components/responses/Generic503"
               security:
                 - {}
                 - notificationsBearerAuth: []
@@ -119,16 +115,10 @@ paths:
           $ref: "#/components/responses/SubscriptionPermissionDenied403"
         "409":
           $ref: "#/components/responses/Generic409"
-        "415":
-          $ref: "#/components/responses/Generic415"
         "422":
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
           $ref: "#/components/responses/Generic429"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     get:
       tags:
         - <apiName> Subscription
@@ -159,10 +149,6 @@ paths:
           $ref: "#/components/responses/Generic401"
         "403":
           $ref: "#/components/responses/Generic403"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
   /subscriptions/{subscriptionId}:
     get:
       tags:
@@ -194,10 +180,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     delete:
       tags:
         - <apiName> Subscription
@@ -233,10 +215,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
 components:
   securitySchemes:
     openId:
@@ -983,22 +961,6 @@ components:
                 status: 410
                 code: GONE
                 message: Access to the target resource is no longer available.
-    Generic415:
-      description: Unsupported Media Type
-      headers:
-        X-Correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
-              description: Payload format of the request is in an unsupported format by the Server. Should not happen
-              value:
-                status: 415
-                code: UNSUPPORTED_MEDIA_TYPE
-                message: The server refuses to accept the request because the payload format is in an unsupported format
     CreateSubscriptionUnprocessableEntity422:
       description: Unprocessable Entity
       headers:
@@ -1048,38 +1010,6 @@ components:
                 status: 429
                 code: TOO_MANY_REQUESTS
                 message: Either out of resource quota or reaching rate limiting.
-    Generic500:
-      description: Server error
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_500_INTERNAL:
-              description: Problem in Server side. Regular Server Exception
-              value:
-                status: 500
-                code: INTERNAL
-                message: Unknown server error. Typically a server bug.
-    Generic503:
-      description: Service unavailable. Typically the server is down.
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_503_UNAVAILABLE:
-              description: Service is not available. Temporary situation usually related to maintenance process in the server side
-              value:
-                status: 503
-                code: UNAVAILABLE
-                message: Service Unavailable.
     SubscriptionIdRequired:
       description: Problem with the client request
       headers:

From 8c4fd0a8602ae5c39e661a413b6fc88e483391db Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Mon, 18 Nov 2024 16:39:35 +0100
Subject: [PATCH 34/45] Update event-subscription-template.yaml (issue326)

Fix https://github.com/camaraproject/Commonalities/issues/326
---
 .../camara-cloudevents/event-subscription-template.yaml   | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 6ad6866a..0b9baf96 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -18,14 +18,12 @@ externalDocs:
   description: Product documentation at CAMARA
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/{apiName}/v0.1"
+  - url: "{apiRoot}/api-name/vx.y"
+  # api-name and version should valued accordingly to the API
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root
-      apiName:
-        default: camaraAPI
-        description: apiName will be replaced in WG by its value and not modelled as a variable
+        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
 tags:
   - name: <apiName> Subscription
     description: Operations to manage event subscriptions on event-type event

From ac994a56e82dd1cecabf3f2fb97937427261760e Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Thu, 21 Nov 2024 18:26:11 +0100
Subject: [PATCH 35/45] Update
 artifacts/camara-cloudevents/event-subscription-template.yaml

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>
---
 artifacts/camara-cloudevents/event-subscription-template.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml
index 0b9baf96..98769daf 100644
--- a/artifacts/camara-cloudevents/event-subscription-template.yaml
+++ b/artifacts/camara-cloudevents/event-subscription-template.yaml
@@ -4,7 +4,7 @@ info:
   description: |
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
-    Note on event name convention: the event type name MUST follow: ``org.camaraproject.<api-name>.<api-version>.<event-name>`` 
+    Note on event name convention: the event type name MUST follow: ``org.camaraproject.<api-name>.<api-version>.<event-name>``
 
     Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type1:grant-level` must be replaced accordingly to the format defined in the guideline document.
 

From f3d5e46d18ec3ca29a79881c8234add927928231 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 22 Nov 2024 13:28:23 +0100
Subject: [PATCH 36/45] Update documentation/API-design-guidelines.md

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>
---
 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 1a1a618f..cbc4ab9a 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1573,7 +1573,7 @@ The decision on the API-level scopes was made within the [Identity and Consent M
 The scopes will always be those defined in the API Specs YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API Spec YAML file and agreed in the corresponding API subproject. 
 
 
-### 11.7 API access restriction (Based on token & client Id)
+### 11.7 Resource access restriction 
 
 In some CAMARA APIs there are functions to create resource (via POST) and then later query them via id and/or list (with GET) or delete them (via DELETE). For example we have sessions, payments, subscriptions, etc..
 

From 2e08ef7c63db8dddc06b5382d2109e7d57a3d799 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 22 Nov 2024 13:28:34 +0100
Subject: [PATCH 37/45] Update documentation/API-design-guidelines.md

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>
---
 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 cbc4ab9a..6a8cd1a7 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1747,7 +1747,7 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 
 
 **Note** on combined usage of initialEvent and subscriptionMaxEvents: 
-Unless explicitly decided otherwise by the API WG,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
+Unless explicitly decided otherwise by the API Sub Project,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
 It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
 
 **Subscription status value table**:

From 56361168e7e7d89a1481657ede8cfc2984952ce2 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Fri, 22 Nov 2024 16:48:55 +0100
Subject: [PATCH 38/45] 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 <pedro.diezgarcia@telefonica.com>
---
 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 6a8cd1a7..b7e259e2 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1747,7 +1747,7 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 
 
 **Note** on combined usage of initialEvent and subscriptionMaxEvents: 
-Unless explicitly decided otherwise by the API Sub Project,  if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
+Unless explicitly decided otherwise by the API Sub Project, if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
 It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
 
 **Subscription status value table**:

From cfe5135ed893b7ef1c5ca044325484d170a238c0 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Sun, 24 Nov 2024 18:26:37 +0100
Subject: [PATCH 39/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 b7e259e2..a93ffd11 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1583,7 +1583,7 @@ For the GET and DELETE operations we must restrict the resource(s) targeted depe
 
 | Operation |  3-legged access token is used | 2-legged access token is used |
 |-----------|--------------------------------|-------------------------------|
-| GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must must have been created by the same API client given in the access token. | - The resource queried must have been created by the same API client given in the access token. |
+| GET/{id} | - The resource queried must have been created for the end user associated with the access token. <br> - The resource queried must have been created by the same API client given in the access token. | - The resource queried must have been created by the same API client given in the access token. |
 | GET/ | - Return all resource(s) created by the API consumer that are associated with both the end user identified by the access token and the same API client given in the access token. | - Return all resource(s) created by the same API client given in the access token. |
 | DELETE/{id} | - The resource to be deleted must have been created for the end user associated with the access token. <br> - The resource to be deleted must have been created by the same API client given in the access token. | - The resource to be deleted must have been created by the same API client given in the access token. |
 

From 9cf747ae3ba3fffd08f0642097de34c70d0536af Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Sun, 24 Nov 2024 18:26:47 +0100
Subject: [PATCH 40/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 a93ffd11..f5f34ef1 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1700,7 +1700,7 @@ These rules apply for subscription with device identifier
 - If 3-legged access token is used, the POST and GET responses must not provide any device identifier.
 - If 2-legged access token is used, the presence of a device identifier in the response is mandatory and should be the same identifier type than the one provided in the request.
 
-Application of data minimization design must be considered by the API working group for event structure definition.
+Application of data minimization design must be considered by the API Sub Project for event structure definition.
 
 ##### Subscriptions data model
 The following table provides `/subscriptions` attributes

From 2b278aa8fb5d542722f9047fc468d05dd3b06c8b Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Sun, 24 Nov 2024 18:27:00 +0100
Subject: [PATCH 41/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 f5f34ef1..a32b6c2a 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1748,7 +1748,7 @@ Remark: This action will trigger a subscription-ends event with terminationReaso
 
 **Note** on combined usage of initialEvent and subscriptionMaxEvents: 
 Unless explicitly decided otherwise by the API Sub Project, if an event is triggered following initialEvent set to `true`, this event will be counted towards subscriptionMaxEvents (if provided).
-It is recommended to provide this clarification in all subscriptions API featuring subscriptionMaxEvents and initialEvent.
+It is recommended to provide this clarification in all subscription APIs featuring subscriptionMaxEvents and initialEvent.
 
 **Subscription status value table**:
 

From dc5f9faf138064abee503910cb72037622049338 Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Sun, 24 Nov 2024 18:27:11 +0100
Subject: [PATCH 42/45] Update documentation/API-design-guidelines.md

Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com>
---
 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 a32b6c2a..57ccd3cf 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -1913,7 +1913,7 @@ Note: For operational and troubleshooting purposes it is relevant to accommodate
 #### subscription-ends event
 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, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml (see in [Commonalities/artifacts/camara-cloudevents](/artifacts/camara-cloudevents) directory ``event-subscription-template.yaml``). 
+It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notifications prematurely, or if the subscription request is managed asynchronously by the server and it is not able to provide the service. For this specific event, the `data` must feature `terminationReason` attribute. An enumeration of `terminationReason` is provided in event-subscription-template.yaml (see in [Commonalities/artifacts/camara-cloudevents](/artifacts/camara-cloudevents) directory ``event-subscription-template.yaml``). 
 
 Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example, if a client request a `subscriptionMaxEvents` to 2, later, received second notification, then a third notification will be sent for "subscription-ends")
 

From 35737cfed9978bce14735e96b81827978a2985da Mon Sep 17 00:00:00 2001
From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com>
Date: Sun, 24 Nov 2024 18:37:33 +0100
Subject: [PATCH 43/45] Fixe title 11

---
 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 57ccd3cf..772aa4c1 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -66,7 +66,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
           - [Examples](#examples)
         - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions)
         - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara)
-    - [11.7 API access restriction (Based on token \& client Id)](#117-api-access-restriction-based-on-token--client-id)
+    - [11.7 API access restriction](#117-api-access-restriction-based-on-token--client-id)
   - [12. Subscription, Notification \& Event](#12-subscription-notification--event)
     - [12.1 Subscription](#121-subscription)
       - [Instance-based (implicit) subscription](#instance-based-implicit-subscription)

From 07d4ff47a63c85ef4e595423b9ee5f4093dc567b Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 25 Nov 2024 15:48:39 +0100
Subject: [PATCH 44/45] Update API-design-guidelines.md

Link in ToC
---
 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 772aa4c1..9448fb26 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -66,7 +66,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
           - [Examples](#examples)
         - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions)
         - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara)
-    - [11.7 API access restriction](#117-api-access-restriction-based-on-token--client-id)
+    - [11.7 API access restriction](#117-api-access-restriction)
   - [12. Subscription, Notification \& Event](#12-subscription-notification--event)
     - [12.1 Subscription](#121-subscription)
       - [Instance-based (implicit) subscription](#instance-based-implicit-subscription)

From 54e561d085fdfba94a0bfe7fc429feadd8ae70c1 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 25 Nov 2024 15:50:46 +0100
Subject: [PATCH 45/45] Update 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 9448fb26..5bb2fc1d 100644
--- a/documentation/API-design-guidelines.md
+++ b/documentation/API-design-guidelines.md
@@ -66,7 +66,7 @@ This document captures guidelines for the API design in CAMARA project. These gu
           - [Examples](#examples)
         - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions)
         - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara)
-    - [11.7 API access restriction](#117-api-access-restriction)
+    - [11.7 Resource access restriction](#117-resource-access-restriction)
   - [12. Subscription, Notification \& Event](#12-subscription-notification--event)
     - [12.1 Subscription](#121-subscription)
       - [Instance-based (implicit) subscription](#instance-based-implicit-subscription)