diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index c9e8fad..6f4f639 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -5,23 +5,39 @@ info: The API can be used to check whether the subscriber of the phone number has changed. A common scenario is when Application service provider (ASP) wants to check whether there has been a change in the user associated with the phone number after the specified date. This allows the ASP to ensure that a phone number is correctly linked to an user and prevent the mis-delivery of SMS messages. - For example, below is a potential scenario (see the figure below): - * Pre-conditions - * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and canceled it on February 25, 2024. Subsequently, User B signed a contract with MNO A for the same phone number on September 21, 2024, and is still using it. - * User A also signed contracts with ASP A on December 22, 2023 for its services. - * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A. - * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A. - * Potential operations - * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API. - * The API response sets to 'true', indicating that there has been a change in the user associated with the phone number. - * Post-conditions - * ASP A decides to stop sending the SMS message to User A and contacts User A by mail. - * By following these steps, ASP A ensures that a phone number is not linked to User A and prevents the mis-delivery of the SMS message. + For example, below is a potential scenarios: + * Scenario 1 + * Pre-conditions + * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and is still using it. + * User A also signed contracts with ASP A on December 22, 2023 for its services. + * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A. + * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A. + * Potential operations + * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API. + * The API response sets to 'false', indicating that there has not been a change in the user associated with the phone number. + * Post-conditions + * ASP A decides to send the SMS message to User A. + * By following these steps, ASP A ensures that a phone number is linked to User A. - Number_Recycling_scenario + Number_Recycling_scenario_1 + + * Scenario 2 + * Pre-conditions + * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and canceled it on February 25, 2024. Subsequently, User B signed a contract with MNO A for the same phone number on September 21, 2024, and is still using it. + * User A also signed contracts with ASP A on December 22, 2023 for its services. + * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A. + * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A. + * Potential operations + * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API. + * The API response sets to 'true', indicating that there has been a change in the user associated with the phone number. + * Post-conditions + * ASP A decides to stop sending the SMS message to User A and contacts User A by mail. + * By following these steps, ASP A ensures that a phone number is not linked to User A and prevents the mis-delivery of the SMS message. + + Number_Recycling_scenario_2 Note: - * When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(see the scenerio in the figure above). + * When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(e.g., the period between 2024-02-25 and 2024-09-21 in the Scenario 2 of the figure above). ### Authorization and authentication