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. Actual api-processor version can be "unknown"
3. 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 the same as actual one. Therefore, it was decided to perform migration every time when new version of api-processor released.
4. Current story consider cases when downgrade of api-processor version is possible.
5. 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.
   • 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: "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

2. Case 2: "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

3. Case 3: client api-processor version < be api-processor version.

4. Case 4: client api-processor version > be api-processor version.

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:
     • tooltip for case 1: "The data in the 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."
     • tooltip for case 2: "The data in the version may be incorrect, please contact the system administrators."
     • tooltip for cases 4 & 5: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."

   

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:
     • tooltip for case 1: "The data in the 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."
     • tooltip for case 2: "The data in the version may be incorrect, please contact the system administrators."
     • tooltip for cases 3 & 4: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."

   

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

   • If one of the selected package/revision has one of the problems from the section "Cases with api-processor versions", the system shall show warning message and disable "Compare" button:
     • message for case 1: "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."
     • message for case 2: "The data in the version <'version'> may be incorrect, please contact the system administrators."
     • message for cases 3 & 4: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."
   • for cases 1 & 2, if both versions/revisions have api-processor versions problem, then warning message shall be displayed for version/revision from the "current" field.

   

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 package/revision has one of the problems from the section "Cases with api-processor versions", the system shall show warning icon with tooltip on hover:
     • tooltip for case 1: "The data in the 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."
     • tooltip for case 2: "The data in the version may be incorrect, please contact the system administrators."
     • tooltip for cases 3 & 4: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."
   • If both compared versions/revisions have the problem with api-processor versions, then the system shall show warning messages for each version/revision.

   

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

   • If selected previous release version has one of the problems from the section "Cases with api-processor versions", the system shall show warning message and disable "Publish"/"Copy" button:
     • message for case 1: "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."
     • message for case 2: "The data in the version <'version'> may be incorrect, please contact the system administrators."
     • message for cases 3 & 4: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."

   

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

   • If selected previous release version has one of the problems from the section "Cases with api-processor versions", the system shall show warning message and disable "Add" button: - message for case 1: "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." - message for case 2: "The data in the version <'version'> may be incorrect, please contact the system administrators." - message for cases 3 & 4: "The data in the version may be incorrect, as the data has not been processed according to the latest system rules. Please clear your browser caches and if this does not help, contact the system administrators."