Netcracker Changes API

openapi: 3.2.0
info:
  title: APIHUB Registry – External Changes API
  description: 'Public-facing API contract for APIHUB. This API is intended for external and integration clients and covers package/catalog operations, publication workflows, search, user/profile actions, and selected administration capabilities secured by APIHUB authentication schemes.

    '
  contact:
    name: Netcracker Opensource Group
    email: opensourcegroup@netcracker.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.1'
  x-api-kind: BWC
servers:
- url: https://{apihub}.qubership.org
  description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
  variables:
    apihub:
      description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
      enum:
      - apihub
      - dev.apihub
      - staging.apihub
      default: apihub
security:
- BearerAuth: []
- CookieAuth: []
- api-key: []
- PersonalAccessToken: []
tags:
- name: Changes
  description: Changes APIs.
paths:
  /api/v2/packages/{packageId}/versions/{version}/changes/summary:
    get:
      tags:
      - Changes
      summary: Get changes summary
      description: 'Get summary of changes between two packages versions.

        '
      operationId: getPackageIdVersionChangesSummary
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  title: packageComparison
                  description: List of changes data.
                  required:
                  - operationTypes
                  properties:
                    operationTypes:
                      type: array
                      items:
                        type: object
                        properties:
                          apiType:
                            $ref: '#/components/schemas/ApiType'
                          numberOfImpactedOperations:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of operations impacted by each severety type.
                          changesSummary:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of declarative changes of each severety type.
                          tags:
                            type: array
                            items:
                              type: string
                            example:
                            - tag1
                            - tag2
                    noContent:
                      type: boolean
                      description: true - operation comparison cache is not stored in database
                      default: false
                    contractsChangesSummary:
                      $ref: '#/components/schemas/VersionComparisonContractsSummary'
                - type: object
                  title: dashboardComparison
                  required:
                  - refs
                  - packages
                  properties:
                    refs:
                      description: "Refs shows which packages in compared dashboards were added/deleted/changed and changes summary for each package:\n  * added package - packageRef is returned\n  * deleted package - previousPackageRef is returned returned\n  * changed package - both packageRef and previousPackageRef are returned\n"
                      type: array
                      items:
                        type: object
                        properties:
                          packageRef:
                            description: 'Parent package and version link.

                              Created by the concatenation of the packageId and version name with At sign.

                              '
                            type: string
                            example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                          previousPackageRef:
                            description: 'Parent package and version link.

                              Created by the concatenation of the packageId and version name with At sign.

                              '
                            type: string
                            example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                          operationTypes:
                            type: array
                            items:
                              type: object
                              properties:
                                apiType:
                                  $ref: '#/components/schemas/ApiType'
                                numberOfImpactedOperations:
                                  allOf:
                                  - $ref: '#/components/schemas/ChangeSummary'
                                  - type: object
                                    description: Number of operations impacted by each severety type.
                                changesSummary:
                                  allOf:
                                  - $ref: '#/components/schemas/ChangeSummary'
                                  - type: object
                                    description: Number of declarative changes of each severety type.
                                tags:
                                  type: array
                                  items:
                                    type: string
                                  example:
                                  - tag1
                                  - tag2
                          noContent:
                            type: boolean
                            description: true - operation comparison cache is not stored in database
                            default: false
                          contractsChangesSummary:
                            $ref: '#/components/schemas/VersionComparisonContractsSummary'
                    packages:
                      $ref: '#/components/schemas/PackagesMap'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v4/packages/{packageId}/versions/{version}/{apiType}/changes:
    get:
      tags:
      - Changes
      summary: Get list of changed operations
      description: 'Get changes between two compared package versions with details by operations.\

        The result list depends on the API type.

        '
      operationId: getPackagesIdVersionsIdApiTypeChangesV4
      parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/apiAudience'
      - $ref: '#/components/parameters/asyncapiChannel'
      - $ref: '#/components/parameters/asyncapiProtocol'
      - $ref: '#/components/parameters/severity'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      - name: version
        in: path
        description: 'Package version.

          The mask <version>@<revision> may be used for search in a specific revision.

          '
        required: true
        schema:
          type: string
          example: 2022.3@3
      - name: refPackageId
        description: Filter by package id of ref package and previous ref package.
        in: query
        schema:
          type: string
      - name: apiKind
        description: Filter by api kind
        in: query
        schema:
          type: string
          enum:
          - bwc
          - no-bwc
          - experimental
      - name: documentSlug
        in: query
        description: Document unique string identifier
        schema:
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
      - name: tag
        in: query
        schema:
          type: string
        description: 'A full match is required.\

          Multiple tags separated by comma can be specified.

          '
      - name: emptyTag
        in: query
        description: 'Flag, filtering the operations without tags at all.

          In response will be returned the list of operations, on what the tag is not filled in.

          This attribute has a higher priority than the **tag**. In case, then **emptyTag: true**, it will override the **tag** filter.

          '
        schema:
          type: boolean
          default: false
      - name: group
        in: query
        description: 'Name of the group for filtering.\

          The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

          Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

          '
        schema:
          type: string
          example: v1
      - name: emptyGroup
        in: query
        description: 'Flag for filtering operations without a group.\

          The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

          Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

          '
        schema:
          type: boolean
          default: false
      - name: textFilter
        in: query
        description: 'Filter by operation''s title/path/method.

          For AsyncAPI: searches by message title(or messageId), channel title(or channelId) or operation action.

          '
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - operations
                properties:
                  previousVersion:
                    description: Name of the previous published version. The <version>@<revision> mask is used to return the revision number.
                    type: string
                    example: 2022.2@5
                  previousVersionPackageId:
                    description: Previous release version package id.
                    type: string
                    example: QS.CloudQSS.CPQ.Q-TMF
                  operations:
                    type: array
                    items:
                      allOf:
                      - oneOf:
                        - title: RestOperation
                          type: object
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/RestOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/RestOperationInfoFromDifferentVersions'
                        - title: GraphQLOperation
                          type: object
                          required:
                          - type
                          - method
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/GqlOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/GqlOperationInfoFromDifferentVersions'
                        - title: AsyncAPIOperation
                          description: AsyncAPI 3.0 operation change entry. Type-specific fields (action, channel, protocol) are inside previousOperation/currentOperation.
                          type: object
                          properties:
                            previousOperation:
                              $ref: '#/components/schemas/AsyncAPIOperationInfoFromDifferentVersions'
                            currentOperation:
                              $ref: '#/components/schemas/AsyncAPIOperationInfoFromDifferentVersions'
                      - type: object
                        required:
                        - changeSummary
                        - comparisonInternalDocumentId
                        properties:
                          changeSummary:
                            allOf:
                            - $ref: '#/components/schemas/ChangeSummary'
                            - type: object
                              description: Number of declarative changes in one specific operation.
                          comparisonInternalDocumentId:
                            description: 'Unique string identifier of the internal merged document, where diffs between operation and previous operation are present. Corresponds to `id` field for the document in `comparison-internal-documents.json`

                              '
                            type: string
                            pattern: ^[a-z0-9-]
                            example: qitmf-v5-11-qitmf-v5-12-merged-json
                  packages:
                    $ref: '#/components/schemas/PackagesMap'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/changes:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/apiType'
    - $ref: '#/components/parameters/apiAudience'
    - $ref: '#/components/parameters/asyncapiChannel'
    - $ref: '#/components/parameters/asyncapiProtocol'
    - $ref: '#/components/parameters/severity'
    - $ref: '#/components/parameters/previousVersion'
    - $ref: '#/components/parameters/previousVersionPackageId'
    - name: refPackageId
      description: Filter by package id of ref package and previous ref package.
      in: query
      schema:
        type: string
    - name: apiKind
      description: Filter by api kind
      in: query
      schema:
        type: string
        enum:
        - bwc
        - no-bwc
        - experimental
    - name: tag
      in: query
      schema:
        type: string
      description: 'A full match is required.\

        Multiple tags separated by comma can be specified.

        '
    - name: emptyTag
      in: query
      description: 'Flag, filtering the operations without tags at all.

        In response will be returned the list of operations, on what the tag is not filled in.

        This attribute has a higher priority than the **tag**. In case, then **emptyTag: true**, it will override the **tag** filter.

        '
      schema:
        type: boolean
        default: false
    - name: group
      in: query
      description: 'Name of the group for filtering.\

        The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

        Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

        '
      schema:
        type: string
        example: v1
    - name: emptyGroup
      in: query
      description: 'Flag for filtering operations without a group.\

        The filter is applied only to the groups of current version. Groups from previous version will be ignored.\

        Either "group" or "emptyGroup" (= true) can be sent in the request, if both of them are specified then 400 will be returned in the response.

        '
      schema:
        type: boolean
        default: false
    - name: textFilter
      in: query
      description: 'Filter by operation''s title/path/method.

        For AsyncAPI: searches by message title(or messageId), channel title(or channelId) or operation action.

        '
      schema:
        type: string
    get:
      tags:
      - Changes
      summary: Export API changes to xlsx file
      description: Export API changes to xlsx file
      operationId: getPackageIdVersionIdChangesExportV3
      responses:
        '200':
          description: Success
          content:
            application/xlsx:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="APIChanges_package.id_version.xlsx"
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/versions/{version}/changes/export:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/previousVersion'
    - $ref: '#/components/parameters/previousVersionPackageId'
    - name: format
      in: query
      description: File format for export
      schema:
        type: string
        enum:
        - xlsx
        default: xlsx
    get:
      tags:
      - Changes
      summary: Export API changes to xlsx file
      description: Export API changes to xlsx file
      operationId: getPackageIdVersionIdChangesExport
      responses:
        '200':
          description: Success
          content:
            application/xlsx:
              schema:
                type: string
                format: binary
                description: xlsx file to download
          headers:
            Content-Disposition:
              schema:
                type: string
                description: xlsx file name
                example: attachment; filename="APIChanges_package.id_version.xlsx"
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/compare:
    post:
      tags:
      - Changes
      summary: Version changelog async calculation
      description: 'Calculate changes between any two packages/versions/revisions for any type of API.


        * **200 Comparison calculated successfully** if there is such comparison.


        * **202 Accepted** will be returned after starting of the async changelog calculation.

        '
      operationId: postCompare
      parameters:
      - name: clientBuild
        in: query
        description: Client-side package build will be used.
        required: false
        schema:
          type: boolean
          default: false
      - name: builderId
        in: query
        required: false
        description: Builder identifier. **Required** if clientBuild=true.
        schema:
          type: string
      - name: reCalculate
        in: query
        description: 'Flag for the force changelog re-calculation.

          May be used after the previous API call with **error** status.

          '
        schema:
          type: boolean
          default: false
      requestBody:
        description: Changelog calculation parameters.
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - packageId
              - version
              - previousVersionPackageId
              - previousVersion
              properties:
                packageId:
                  description: Package unique identifier (full alias).
                  type: string
                  example: QS.CQSS.CPQ.TMF
                version:
                  description: 'Package version.

                    The mask <version>@<revision> may be used for search in a specific revision.


                    If the @revision is not provided, the latest version''s revision will be used.

                    '
                  type: string
                  example: 2022.3@3
                previousVersionPackageId:
                  description: Package id of the previous version to compare with.
                  type: string
                  example: QS.CloudQSS.CPQ.Q-TMF
                previousVersion:
                  description: 'Name of the previous published version to compare with.

                    The mask <version>@<revision> may be used for search in a specific revision.


                    If the @revision is not provided, the latest version''s revision will be used.

                    '
                  type: string
                  example: 2022.2@4
      responses:
        '200':
          description: Comparison calculated successfully
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                description: build config
                properties:
                  packageId:
                    description: Package unique identifier (full alias).
                    type: string
                    example: QS.CQSS.CPQ.TMF
                  version:
                    description: 'Package version.

                      The mask <version>@<revision> will be used for return in a specific revision.


                      If the @<revision> was not transmitted in the request - it won''t be returned in response. Consider the version as the latest one.

                      '
                    type: string
                    example: 2022.3@3
                  previousVersionPackageId:
                    description: Previous release version package id.
                    type: string
                    example: QS.CloudQSS.CPQ.Q-TMF
                  previousVersion:
                    description: 'Name of the previous published version.

                      The mask <version>@<revision> will be used for return a specific revision.


                      If the @<revision> was not transmitted in the request - it won''t be returned in response. Consider the version as the latest one.

                      '
                    type: string
                    example: 2022.2@4
                  buildType:
                    description: 'Type of the build process. Available options are:

                      **changelog** - Only the changelog calculation, no API contracts version will be created.

                      '
                    type: string
                    enum:
                    - changelog
                  createdBy:
                    description: User, created the changelog build.
                    type: string
                  buildId:
                    description: Id of the created build.
                    type: string
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Calculation process status.
                    type: string
                    enum:
                    - running
                    - error
                  message:
                    description: The message for **error** status.
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/versions/{version}/ddl/entities/{ddlEntityId}/changes:
    get:
      tags:
      - Changes
      summary: Get DDL entity changes
      description: Get changes of one DDL entity between current and previous published package versions. Only `table` entities are supported now.
      operationId: getPackageVersionDdlEntityChanges
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/ddlEntityId'
      - $ref: '#/components/parameters/severity'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      - in: query
        name: previousVersionDdlEntityId
        description: DDL entity identifier from previous version.\ Empty, if requested entity is added in the current version; otherwise, must be specified.
        schema:
          type: string
          example: public-table-accounts
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  changes:
                    description: List of individual DDL entity changes.
                    type: array
                    items:
                      $ref: '#/components/schemas/SingleOperationChange'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/packages/{packageId}/versions/{version}/ddl/changes:
    get:
      tags:
      - Changes
      summary: Get list of changed DDL entities
      description: 'Get DDL contract changes between two compared package versions with details by entities.

        Only `table` entities are supported now.

        '
      operationId: getPackageVersionDdlChanges
      parameters:
      - $ref: '#/components/parameters/packageId'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/severity'
      - $ref: '#/components/parameters/previousVersion'
      - $ref: '#/components/parameters/previousVersionPackageId'
      - name: refPa

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netcracker/refs/heads/main/openapi/netcracker-changes-api-openapi.yml