From f26f4561a8e8e3620fec10162c70511ab88d9c29 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Fri, 12 Apr 2024 14:29:44 +0200 Subject: [PATCH 01/13] update-design-doc-with-explicit-sub-scope-changes --- documentation/API-design-guidelines.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 5bb0d3ff..c702d3cc 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -949,10 +949,22 @@ The following controls will be performed on the access token: The scopes allow defining the permission scopes that a system or a user has on a resource, ensuring that they can only access the parts they need and not have access to more. These restrictions are done by limiting the permissions that are granted to OAuth tokens. -Scopes should be represented as: +Scopes should be represented as below for all Camara APIs except the APIs that offer explicit event subscriptions: - API Name: address-management, numbering-information... - Protected Resource: orders, billings… - Grant-level, action on resource: read, write… + +The APIs that offer a way to subscribe to events (explicit subscriptions) must have a way to reflect which event types are being subscribed to, when a subscription create request is made. This will impact how consent management is done for these APIs. + +Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: + +- API Name: device-roaming-subscriptions +- Grant-level, action on resource: read, delete + +Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: + +- Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on (As API name is already a part of the event type field, we do not prepend it again within the scope) +- Grant-level, action on resource: create To correctly define the scopes, when creating them, the following recommendations should be taken: - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. @@ -1332,6 +1344,8 @@ Note: It is perfectly valid for a CAMARA API to have several event types managed In order to ease developer adoption, the pattern for Resource-based event subscription should be consistent for all API providing this feature. +To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. The name of this API must be appended with the keyword "subscriptions". For e.g. device-roaming-subscriptions.yaml + 4 operations must be defined: | operation | path | description | From 4a4b2be80d3eb412275e85b008d68ce74d31d3b0 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 16:56:14 +0200 Subject: [PATCH 02/13] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index c702d3cc..7d1d47b4 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -954,17 +954,24 @@ Scopes should be represented as below for all Camara APIs except the APIs that o - Protected Resource: orders, billings… - Grant-level, action on resource: read, write… -The APIs that offer a way to subscribe to events (explicit subscriptions) must have a way to reflect which event types are being subscribed to, when a subscription create request is made. This will impact how consent management is done for these APIs. +For e.g. qod-sessions-read + +The APIs that offer explicit event subscriptions must have a way to reflect which event types are being subscribed to, when a subscription create request is made. This will impact how consent management is handled for these APIs. Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: - API Name: device-roaming-subscriptions - Grant-level, action on resource: read, delete + +For e.g. device-roaming-subscriptions-read Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: +- API Name: device-roaming-subscriptions - Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on (As API name is already a part of the event type field, we do not prepend it again within the scope) - Grant-level, action on resource: create + +For e.g. device-roaming-subscriptions-org.camaraproject.device-roaming-subscriptions.v0.roaming-on-create To correctly define the scopes, when creating them, the following recommendations should be taken: - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. From 43b28d24d020a20cd32f6dbbe6d91cac46d43a55 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 17:30:35 +0200 Subject: [PATCH 03/13] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7d1d47b4..995d18ee 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -954,7 +954,7 @@ Scopes should be represented as below for all Camara APIs except the APIs that o - Protected Resource: orders, billings… - Grant-level, action on resource: read, write… -For e.g. qod-sessions-read +For e.g. qod:sessions:read The APIs that offer explicit event subscriptions must have a way to reflect which event types are being subscribed to, when a subscription create request is made. This will impact how consent management is handled for these APIs. @@ -963,15 +963,15 @@ Scopes should be represented as below for APIs that offer explicit event subscri - API Name: device-roaming-subscriptions - Grant-level, action on resource: read, delete -For e.g. device-roaming-subscriptions-read +For e.g. device-roaming-subscriptions:read Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: - API Name: device-roaming-subscriptions -- Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on (As API name is already a part of the event type field, we do not prepend it again within the scope) +- Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on - Grant-level, action on resource: create -For e.g. device-roaming-subscriptions-org.camaraproject.device-roaming-subscriptions.v0.roaming-on-create +For e.g. device-roaming-subscriptions:org.camaraproject.device-roaming-subscriptions.v0.roaming-on:create To correctly define the scopes, when creating them, the following recommendations should be taken: - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. From 2a6e65e6186a2374f8da911913645d88e9add489 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 17:52:53 +0200 Subject: [PATCH 04/13] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 995d18ee..27ca3aa3 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -950,8 +950,8 @@ The following controls will be performed on the access token: The scopes allow defining the permission scopes that a system or a user has on a resource, ensuring that they can only access the parts they need and not have access to more. These restrictions are done by limiting the permissions that are granted to OAuth tokens. Scopes should be represented as below for all Camara APIs except the APIs that offer explicit event subscriptions: -- API Name: address-management, numbering-information... -- Protected Resource: orders, billings… +- API Name: qod, address-management, numbering-information... +- Protected Resource: sessions, orders, billings… - Grant-level, action on resource: read, write… For e.g. qod:sessions:read @@ -961,6 +961,7 @@ The APIs that offer explicit event subscriptions must have a way to reflect whic Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: - API Name: device-roaming-subscriptions +- Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) - Grant-level, action on resource: read, delete For e.g. device-roaming-subscriptions:read @@ -968,6 +969,7 @@ For e.g. device-roaming-subscriptions:read Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: - API Name: device-roaming-subscriptions +- Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) - Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on - Grant-level, action on resource: create From 235427020f64679f6c1bdd54b89ae004d9e9ba4d Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 17:55:21 +0200 Subject: [PATCH 05/13] 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 27ca3aa3..e690b1a4 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1353,7 +1353,7 @@ Note: It is perfectly valid for a CAMARA API to have several event types managed In order to ease developer adoption, the pattern for Resource-based event subscription should be consistent for all API providing this feature. -To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. The name of this API must be appended with the keyword "subscriptions". For e.g. device-roaming-subscriptions.yaml +To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. It is recommended when possible to append the keyyword "subscriptions" at the end of the API name. For e.g. device-roaming-subscriptions.yaml 4 operations must be defined: From d233de652878fbd8dacc33c42c1cfdf192a7ee46 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 18:07:37 +0200 Subject: [PATCH 06/13] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index e690b1a4..b1e6fd80 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -979,6 +979,7 @@ To correctly define the scopes, when creating them, the following recommendation - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. - **Use a common nomenclature for all resources**. Scopes must be descriptive names and that there is no conflict between the different resources. - **Use the kebab-case nomenclature** to define API names, resources, and scope permissions. +- **Use** ":" as the separator between API name, protected resources, event-types and grant-levels. See section [11.6 Security Definition](#116-security-definition) for detailed guidelines on how to define scopes and other security-related properties in a OpenAPI file. From 51f917c75a6b93b123bae775a7051703dbff558e Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 18:09:30 +0200 Subject: [PATCH 07/13] 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 b1e6fd80..5725c846 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -979,7 +979,7 @@ To correctly define the scopes, when creating them, the following recommendation - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. - **Use a common nomenclature for all resources**. Scopes must be descriptive names and that there is no conflict between the different resources. - **Use the kebab-case nomenclature** to define API names, resources, and scope permissions. -- **Use** ":" as the separator between API name, protected resources, event-types and grant-levels. +- **Using ":" a separator** between API name, protected resources, event-types and grant-levels for consistency. See section [11.6 Security Definition](#116-security-definition) for detailed guidelines on how to define scopes and other security-related properties in a OpenAPI file. From 29d08cd9903b23097c6068ad252a043893b5453d Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 18:10:08 +0200 Subject: [PATCH 08/13] 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 5725c846..adb7949a 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -979,7 +979,7 @@ To correctly define the scopes, when creating them, the following recommendation - **Appropriate granularity**. Scopes should be granular enough to match the types of resources and permissions you want to grant. - **Use a common nomenclature for all resources**. Scopes must be descriptive names and that there is no conflict between the different resources. - **Use the kebab-case nomenclature** to define API names, resources, and scope permissions. -- **Using ":" a separator** between API name, protected resources, event-types and grant-levels for consistency. +- **Use ":" a separator** between API name, protected resources, event-types and grant-levels for consistency. See section [11.6 Security Definition](#116-security-definition) for detailed guidelines on how to define scopes and other security-related properties in a OpenAPI file. From 1c5d6e70e44ce806042f788cbceae886e0c3bba3 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 19:46:11 +0200 Subject: [PATCH 09/13] Update documentation/API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index adb7949a..ef406de1 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -966,7 +966,7 @@ Scopes should be represented as below for APIs that offer explicit event subscri For e.g. device-roaming-subscriptions:read -Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: +The format to define scopes for explicit subscriptions with action create, includes the event type in its formulation to ensure that consent is managed at the level of subscribed event types. Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: - API Name: device-roaming-subscriptions - Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) From 1f0b69e50b246b84bcb929ba11090ee3d6d2d366 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 19:48:46 +0200 Subject: [PATCH 10/13] Update documentation/API-design-guidelines.md --- documentation/API-design-guidelines.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index ef406de1..33275368 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -963,6 +963,7 @@ Scopes should be represented as below for APIs that offer explicit event subscri - API Name: device-roaming-subscriptions - Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) - Grant-level, action on resource: read, delete +This type of formulation is not needed for the create action. For e.g. device-roaming-subscriptions:read From 0468e37a2ba210ad88702c4344e64b1589991567 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 30 Apr 2024 19:49:33 +0200 Subject: [PATCH 11/13] Update documentation/API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 33275368..02f0e434 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1355,7 +1355,7 @@ Note: It is perfectly valid for a CAMARA API to have several event types managed In order to ease developer adoption, the pattern for Resource-based event subscription should be consistent for all API providing this feature. -To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. It is recommended when possible to append the keyyword "subscriptions" at the end of the API name. For e.g. device-roaming-subscriptions.yaml +To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. It is recommended when possible to append the keyword "subscriptions" at the end of the API name. For e.g. device-roaming-subscriptions.yaml 4 operations must be defined: From 9bd80d526224e152dadf3d604be2449c8828a0d5 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Thu, 2 May 2024 16:15:50 +0200 Subject: [PATCH 12/13] Update API-design-guidelines.md-mandate-sub-in-name To makes changes for https://github.com/camaraproject/Commonalities/pull/189#pullrequestreview-2035280513 --- documentation/API-design-guidelines.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 02f0e434..53fbb426 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -961,7 +961,6 @@ The APIs that offer explicit event subscriptions must have a way to reflect whic Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: - API Name: device-roaming-subscriptions -- Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) - Grant-level, action on resource: read, delete This type of formulation is not needed for the create action. @@ -970,7 +969,6 @@ For e.g. device-roaming-subscriptions:read The format to define scopes for explicit subscriptions with action create, includes the event type in its formulation to ensure that consent is managed at the level of subscribed event types. Scopes should be represented as below for APIs that offer explicit event subscriptions with action create: - API Name: device-roaming-subscriptions -- Protected Resource: subscriptions (If the API name offering explicit subscriptions does not include the word subscriptions, then the protected resource "subscriptions" should be added when defining the scope.) - Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on - Grant-level, action on resource: create @@ -1355,7 +1353,7 @@ Note: It is perfectly valid for a CAMARA API to have several event types managed In order to ease developer adoption, the pattern for Resource-based event subscription should be consistent for all API providing this feature. -To ensure consistency across Camara subprojects, it is necessary that explicit subscriptions are handled within separate API/s. It is recommended when possible to append the keyword "subscriptions" at the end of the API name. For e.g. device-roaming-subscriptions.yaml +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 4 operations must be defined: From 7835e5d648ee7fd2e79591e824eac4282512cef5 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Fri, 3 May 2024 09:30:22 +0200 Subject: [PATCH 13/13] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 53fbb426..e5c43153 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1353,7 +1353,7 @@ Note: It is perfectly valid for a CAMARA API to have several event types managed In order to ease developer adoption, the pattern for Resource-based event subscription should be consistent for all API providing this feature. -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 +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 4 operations must be defined: