diff --git a/CHANGELOG.MD b/CHANGELOG.MD new file mode 100644 index 0000000..b577aca --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 0754760..fa8ffa8 100644 --- a/README.md +++ b/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 + +* 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). + +
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) diff --git a/code/API_definitions/README.MD b/code/API_definitions/README.MD deleted file mode 100644 index 04313f1..0000000 --- a/code/API_definitions/README.MD +++ /dev/null @@ -1 +0,0 @@ -Here you can add your definitions and delete this README.MD file diff --git a/code/API_definitions/subscription-status.yaml b/code/API_definitions/subscription-status.yaml index 694401a..038cfab 100644 --- a/code/API_definitions/subscription-status.yaml +++ b/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 diff --git a/code/Test_definitions/README.md b/code/Test_definitions/README.md deleted file mode 100644 index 27a1f06..0000000 --- a/code/Test_definitions/README.md +++ /dev/null @@ -1 +0,0 @@ -This directory contains at least one `.feature` file containing test definitions for the repository API(s). diff --git a/code/Test_definitions/subscription-status.feature b/code/Test_definitions/subscription-status.feature index ec4530a..52195f9 100644 --- a/code/Test_definitions/subscription-status.feature +++ b/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" \ No newline at end of file + And the response contains error code "SERVICE_NOT_APPLICABLE" diff --git a/documentation/API_documentation/README.MD b/documentation/API_documentation/README.MD deleted file mode 100644 index 37aa0ff..0000000 --- a/documentation/API_documentation/README.MD +++ /dev/null @@ -1 +0,0 @@ -This README.MD can be deleted when the first file is added to this directory. diff --git a/documentation/API_documentation/subscription-status-API-Readiness-Checklist.md b/documentation/API_documentation/subscription-status-API-Readiness-Checklist.md new file mode 100644 index 0000000..bc92243 --- /dev/null +++ b/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
public | stable
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) |