Fall25 - M3 Milestone - r1.1 - version v0.1.0 Release Candidate

CHANGELOG.MD

@@ -0,0 +1,51 @@
+# Changelog Subscription Status
+
+## Table of Contents
+- **[r1.1](#r11)**
+
+**Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.**
+
+The below sections record the changes for each API version in each release as follows:
+
+* for an alpha release, the delta with respect to the previous release
+* for the first release-candidate, all changes since the last public release
+* for subsequent release-candidate(s), only the delta to the previous release-candidate
+* for a public release, the consolidated changes since the previous public release
+
+
+# r1.1
+
+## Release Notes
+
+
+This release contains the definition and documentation of
+* subscription-status v0.1.0-rc.1
+
+The API definition(s) are based on
+* Commonalities v0.6.0-rc.1
+* Identity and Consent Management v0.4.0-rc.1
+
+
+
+## subscription-status v0.1.0-rc.1
+
+**subscription-status v0.1.0-rc.1 is the first release-candidate version for v0.1.0 of the Subscription Status API.
+
+
+ API definition **with inline documentation**:
+[[YAML]](https://github.com/camaraproject/SubscriptionStatus/blob/r1.1/code/API_definitions/subscription-status.yaml)
+[[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SubscriptionStatus/r1.1/code/API_definitions/subscription-status.yaml&nocors)
+[[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/SubscriptionStatus/r1.1/code/API_definitions/subscription-status.yaml)
+
+**Initial contribution of API definitions for Subscription Status**, including initial documentation.
+
+## Added
+* Initial yaml file including Subscription Status API by @chinaunicomyangfan in https://github.com/camaraproject/SubscriptionStatus/pull/6
+* Add test file by @chinaunicomyangfan in https://github.com/camaraproject/SubscriptionStatus/pull/9
+* Add text on undocumented errors to OAS definition by @chinaunicomyangfan in https://github.com/camaraproject/SubscriptionStatus/pull/13
+
+## Removed
+* Remove AUTHENTICATION_REQUIRED error code by @chinaunicomyangfan in https://github.com/camaraproject/SubscriptionStatus/pull/13
+
+## Changed
+* Update x-correlator format by @chinaunicomyangfan in https://github.com/camaraproject/SubscriptionStatus/pull/13

README.md

@@ -17,7 +17,7 @@ Sandbox API Repository to describe, develop, document, and test the Subscription
 
 * Service API “SubscriptionStatus” (see [APIBacklog.md](https://github.com/camaraproject/APIBacklog/blob/main/documentation/APIbacklog.md))
 * The API provides the customer with the ability to:  
-  * obtain the current subscription status of a certain phone number, including the subscription of Voice/SMS in, Voice/SMS out, and data service
+  * obtain the current subscription status of a certain phone number, including the subscription of Voice/SMS Inbound, Voice/SMS Outbound, and Data Service Status
 * Describe, develop, document, and test the APIs
 * Started: August 2024
 
@@ -30,6 +30,18 @@ The repository has no (pre)releases yet, work in progress is within the main bra
 <!-- The latest public release is available here: https://github.com/camaraproject/SubscriptionStatus/releases/latest -->
 <!-- For changes see [CHANGELOG.md](https://github.com/camaraproject/SubscriptionStatus/blob/main/CHANGELOG.md) -->
 
+
+* Note: Please be aware that the project will have updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
+
+ * Pre-release r1.1 with version 0.1.0-rc.1 of the API subscription-status is available [here](https://github.com/camaraproject/SubscriptionStatus/tree/r1.1).
+
+ <br>This is a release candidate version of the API. Until the public release there are bug fixes to be expected. The release candidate is suitable for implementors, but it is not recommended to use the API with customers in productive environments.
+  [[YAML]](https://github.com/camaraproject/SubscriptionStatus/blob/r1.1/code/API_definitions/subscription-status.yaml)
+  [[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/SubscriptionStatus/r1.1/code/API_definitions/subscription-status.yaml&nocors)
+  [[View it on Swagger Editor]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/SubscriptionStatus/r1.1/code/API_definitions/subscription-status.yaml)
+
+* For changes see [CHANGELOG.md](https://github.com/camaraproject/SubscriptionStatus/blob/main/CHANGELOG.md)
+
 ## Contributing
 * Meetings of Sub Project KnowYourCustomer are held virtually 
     * Schedule: Bi-weekly, Tuesday, 09:00 CEST (07:00 UTC)

code/API_definitions/subscription-status.yaml

@@ -63,14 +63,22 @@ info:
     Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.
     As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
 
-  version: wip
+    # Authorization and authentication
+    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
+    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.
+    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
+
+  version: 0.1.0-rc.1
+
   x-camara-commonalities: 0.6
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-
+externalDocs:
+  description: Product documentation at CAMARA
+  url: https://github.com/camaraproject/SubscriptionStatus
 servers:
-  - url: "{apiRoot}/subscription-status/wip"
+  - url: "{apiRoot}/subscription-status/v0.1rc1"
     variables:
       apiRoot:
         default: http://localhost:9091
@@ -84,6 +92,8 @@ paths:
             - subscription-status:retrive-subscription-status
       tags:
         - Retrive Subscription Status
+      description: |
+        Obtain the business subscription status of the provided phone number, including Voice/SMS inbound, Voice/SMS outbound, and data service status.
       operationId: retriveSubscriptionStatus
       summary: Retrieve subscription status of a phone number
       parameters:
@@ -105,7 +115,7 @@ paths:
           description: Subscription status retrieved successfully
           headers:
             x-correlator:
-              $ref: "#/components/headers/X-Correlator"
+              $ref: "#/components/headers/x-correlator"
           content:
             application/json:
               schema:
@@ -132,18 +142,17 @@ components:
       in: header
       description: Correlation ID for cross-service tracking
       schema:
-        type: string
-        pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
-        example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
+        $ref: "#/components/schemas/XCorrelator"
   headers:
-    X-Correlator:
+    x-correlator:
       description: Correlation id for the different services
-      required: false
       schema:
-        type: string
-        pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
-        example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
+        $ref: "#/components/schemas/XCorrelator"
   schemas:
+    XCorrelator:
+      type: string
+      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
+      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
     SubscriptionStatusRequest:
       type: object
       properties:
@@ -194,7 +203,7 @@ components:
       description: Bad Request
       headers:
         x-correlator:
-          $ref: "#/components/headers/X-Correlator"
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -220,7 +229,7 @@ components:
       description: Unauthorized
       headers:
         x-correlator:
-          $ref: "#/components/headers/X-Correlator"
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -246,7 +255,7 @@ components:
       description: Forbidden
       headers:
         x-correlator:
-          $ref: "#/components/headers/X-Correlator"
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -261,8 +270,6 @@ components:
                     enum:
                       - PERMISSION_DENIED
                       - INVALID_TOKEN_CONTEXT
-                      - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_REQUIRED
-                      - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_MISMATCH
           examples:
             GENERIC_403_PERMISSION_DENIED:
               description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
@@ -276,24 +283,12 @@ components:
                 status: 403
                 code: INVALID_TOKEN_CONTEXT
                 message: "phoneNumber is not consistent with access token."
-            KNOW_YOUR_CUSTOMER.ID_DOCUMENT_REQUIRED:
-              description: The idDocument is required by the implementation
-              value:
-                status: 403
-                code: KNOW_YOUR_CUSTOMER.ID_DOCUMENT_REQUIRED
-                message: The idDocument is required to perform the properties validation
-            KNOW_YOUR_CUSTOMER.ID_DOCUMENT_MISMATCH:
-              description: idDocument mismatch
-              value:
-                status: 403
-                code: KNOW_YOUR_CUSTOMER.ID_DOCUMENT_MISMATCH
-                message: The idDocument needs to match the one associated with the provided phoneNumber
 
     Generic404:
       description: Not found
       headers:
         x-correlator:
-          $ref: "#/components/headers/X-Correlator"
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -319,7 +314,7 @@ components:
       description: Unprocessable Content
       headers:
         x-correlator:
-          $ref: "#/components/headers/X-Correlator"
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -354,6 +349,3 @@ components:
                 status: 422
                 code: UNNECESSARY_IDENTIFIER
                 message: An explicit phone number has been provided when one is already associated with the access token
-externalDocs:
-  description: Camara Project Documentation
-  url: https://github.com/camaraproject/SubscriptionStatus

code/Test_definitions/subscription-status.feature

@@ -1,10 +1,11 @@
-Feature: CAMARA SubscriptionStatus API, vwip - Retrieve subscription status of a phone number
+Feature: CAMARA SubscriptionStatus API, v0.1.0-rc.1 - Retrieve subscription status of a phone number
+
 
 Background: Common setup
-    Given the endpoint "{apiRoot}/subscription-status/wip/retrive-subscription-status"
+    Given the resource "/subscription-status/v0.1rc1/retrieve-subscription-status"
     And the header "Content-Type" is set to "application/json"
     And the header "Authorization" is set to a valid access token
-    And the header "x-correlator" is set to a UUID value
+    And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator"
 
 # Happy path scenarios
 
@@ -67,4 +68,4 @@ Scenario: Error when service not available
     And the request body contains this phone number
     When the HTTP "POST" request is sent
     Then the response status code is 422
-    And the response contains error code "SERVICE_NOT_APPLICABLE"
+    And the response contains error code "SERVICE_NOT_APPLICABLE"

documentation/API_documentation/subscription-status-API-Readiness-Checklist.md

@@ -0,0 +1,19 @@
+# API Readiness Checklist
+
+Checklist for subscription-status v0.1.0-rc.1 in r1.1
+
+| Nr | API release assets  | alpha | release-candidate |  initial<br>public | stable<br> public | Status | Reference information |
+|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
+|  1 | API definition                               |   M   |         M         |    M    |    M   |  Y   | [link](/code/API_definitions/subscription-status.yaml) |
+|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   |  Y   | [r3.2](https://github.com/camaraproject/Commonalities/releases/tag/r3.2) |
+|  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |  Y   | [r3.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2) |
+|  4 | API versioning convention applied            |   M   |         M         |    M    |    M   |   Y  | v0.1.0-rc.1     |
+|  5 | API documentation                            |   M   |         M         |    M    |    M   |   Y  | Embed documentation into API spec - [link](/code/subscription-status.yaml) |
+|  6 | User stories                                 |   O   |         O         |    O    |    M   |   N  | 	 |		
+|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   |   Y  | [link](/code/Test_definitions/subscription-status.feature)  |
+|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |   Y  | [link](/code/Test_definitions/subscription-status.feature)  |
+|  9 | Test result statement                        |   O   |         O         |    O    |    M   |   N  |  To be provided    |
+| 10 | API release numbering convention applied     |   M   |         M         |    M    |    M   |   Y  |      |
+| 11 | Change log updated                           |   M   |         M         |    M    |    M   |   Y  | [link](/CHANGELOG.md) |
+| 12 | Previous public release was certified        |   O   |         O         |    O    |    M   |   N  |      |
+| 13 | API description (for marketing)              |   O   |         O         |    M    |    M   |      | [wiki link](https://lf-camaraproject.atlassian.net/wiki/x/hACbBQ) |