DI‐Portal‐GF‐009 Relevance of API‐Processor Versions

Design Item ID: DI-Portal-GF-009
Design Item Name: Relevance of API-Processor Versions
Related Design Items:
Related API:

• Get system info (GET /api/v1/system/info)
• Get package version content (GET /api/v3/packages/{packageId}/versions/{version})
• Get package versions list (GET /api/v3/packages/{packageId}/versions)

Revision History:

Date	Description
22.05.2025	Initial version for https://github.com/Netcracker/qubership-apihub/issues/229, https://github.com/Netcracker/qubership-apihub/issues/230

Assumptions:

1. The requirements are applicable to both packages and dashboards; further using the word package will mean both packages and dashboards.
2. Currently, there are cases when new api-processor version was released, but no migration was performed. So in this case api-processor version of builded revision will not be the same as actual one. Therefore, it was decided to perform migration every time when new version of api-processor released.
3. Current story consider cases when downgrade of api-processor version is possible.
4. The requirements are applicable only to the state when migration is not running.

Requirements

1. The system shall be able compare api-processor version on the client, on the backend and the one with which the current version was builded and warn a user about problem in package version data if api-processor versions do not match.
   • The system shall compare api-processor versions for equality only if migration is not in progress.
     • API to check if migration is in progress - GET /api/v1/system/info:
       • if migrationInProgress = false, then migration is not currently in progress.
   • The system shall compare api-processor versions for equality only if all these versions are release versions.
   • Appropriate locations where warning messages shall be displayed see in section "Locations where warning messages are displayed".
   • Сases of api-processor versions mismatch see in "Cases with api-processor versions mismatch" section.
   • API to get api-processor version on backend - GET /api/v1/system/info.
   • API to get api-processor version with which package version was builded:
     • in specific version - GET /api/v3/packages/{packageId}/versions/{version}.
     • in package versions list - GET /api/v3/packages/{packageId}/versions.

Cases with api-processor versions mismatch:

1. Case 1 - up-to date frontend/backend, outdated build:
   "client api-processor version = be api-processor version" & "revision api-processor version < client api-processor version".

   revision api-processor version	client api-processor version	be api-processor version
   1	2	2

   Warning message for version: "The data in the version <version> may be incorrect, as the data has not been processed according to the latest system rules. Please republish the version and if this does not help, contact the system administrators."

2. Case 2 - downgraded frontend/backend, build from the future:
   "client api-processor version = be api-processor version" & "revision api-processor version > client api-processor version".

   revision api-processor version	client api-processor version	be api-processor version
   2	1	1

   Warning message for version: "The data in the version <version> may be incorrect, please contact the system administrators."

3. Case 3 - outdated frontend:
   client api-processor version is not actual.

   Warning message for version: "The data in the version <version> may be incorrect, as the data has not been processed according to the latest system rules. Please reload the page and if this does not help, contact the system administrators."

Locations where warning messages are displayed:

1. Package version page including all tabs (overview, operations, etc.) and menu items (summary, activity history, etc.)

   • If current package version (revision) has one of the problems from the section "Cases with api-processor versions", the system shall show warning icon with tooltip on hover.
     • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
       • in warning messages, = current version.

   

2. Operation's document view (for all available views - doc, simple, etc.)

   • If current package version (revision) has one of the problems from the section "Cases with api-processor versions", the system shall show warning icon with tooltip on hover.
     • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
       • in warning messages, = current version.

   

3. "Select Versions to Compare" and "Select Revisions to Compare" popups:

   • If one of the selected version/revision has one of the problems from the section "Cases with api-processor versions", the system shall show warning message and disable "Compare" button.
   • If both versions/revisions have api-processor versions problem, then warning message shall be displayed for version/revision from the "current" field.
   • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
     • in warning messages, = appropriate version selected in the popup.

   

4. "Compare Packages" (available in case of dashboards comparison only), "Compare Package API", "Compare API" (with comparison of operations content) pages:

   • If one of the compared version/revision has one of the problems from the section "Cases with api-processor versions", the system shall show warning icon with tooltip on hover.
   • If both compared versions/revisions have the problem with api-processor versions, then the system shall show warning messages for each version/revision.
   • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
     • in warning messages, = appropriate compered version.

   

5. "Publish", "Copy Package Version", "Publish as Package Version" popups:

   • If problem from case 3 occurred or if previous release version has problem from case 1 / case 2 (from the section "Cases with api-processor versions"), the system shall show warning message and disable "Publish"/"Copy" button.
     • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
       • in warning messages, = previous release version selected in the popup.

   

6. "Add package popup" popup (available for dashboards only)

   • If selected package version has one of the problems from the section "Cases with api-processor versions", the system shall show warning message and disable "Add" button:
     • Appropriate tooltip messages for each api-processor versions problem see in "Cases with api-processor versions".
       • in warning messages, = version selected in the popup.