feat: enable update for existing v4 apis via import process

[vikrantgravitee]

Issue

https://gravitee.atlassian.net/browse/APIM-12010

Description

Prior to this change, the import mechanism in Gravitee APIM only supported creating new V4 APIs from a Gravitee definition or an OpenAPI/Swagger descriptor. Updating an existing V4 API through the import flow was explicitly blocked — the import button was disabled for V4 APIs in the console.

This PR removes that restriction and introduces full update-via-import support for V4 APIs (HTTP Proxy, Message, and Native types), both from the console UI and the management REST API.

What Was Achieved

• Users can now open the import modal from the General Info page of an existing V4 API and update it by uploading a Gravitee API definition (JSON) or an OpenAPI/Swagger descriptor.
• • The system validates that the imported definition is V4 before applying any changes, rejecting V1/V2 definitions with a clear error.
• • All sub-entities (metadata, pages/documentation, plans with flows) are upserted as part of the update — not just the top-level API fields.

How the System Works Now

Frontend (Console):

1. The "Import" button on api-general-info.component.html was previously disabled for V4 APIs (api.definitionVersion === 'V4'). That condition has been removed so V4 APIs can now trigger the import modal.

2. 2. A new dedicated Angular dialog component ApiImportV4Component (api-import-v4/) handles the V4 update flow. It accepts an ApiImportV4DialogData input containing the apiId, which signals that this is an update operation rather than a create.
3. 3. The component calls either ApiV2Service.importUpdate(apiId, payload) (for Gravitee definitions) or ApiV2Service.importSwaggerApiUpdate(apiId, descriptor) (for OpenAPI specs), which both issue PUT requests to the backend.
      Backend (Management API v2):

4. Two new PUT endpoints have been added to ApiResource.java:

5. • PUT /apis/{apiId}/_import/definition — updates a V4 API from a Gravitee export definition.
6. • PUT /apis/{apiId}/_import/swagger — updates a V4 API from an OpenAPI/Swagger descriptor (the descriptor is first converted to an import definition via the existing OAIToImportApiUseCase).
7. 2. Both endpoints delegate to the new UpdateApiDefinitionUseCase, which:
8. • Validates that the incoming definition is V4 (throws ApiDefinitionVersionNotSupportedException otherwise).
9. • Looks up the existing API by ID (throws ApiNotFoundException if not found).
10. • Delegates the actual update to ImportDefinitionUpdateDomainService.
11. 3. ImportDefinitionUpdateDomainService orchestrates the full update:
12. • Recalculates API definition IDs via ApiIdsCalculatorDomainService.
13. • Calls UpdateApiDomainService.updateV4() for HTTP Proxy/Message APIs or a native-specific update path for Native APIs.
14. • Updates pictures and background images.
15. • Upserts metadata, documentation pages, and plans with flows.
16. 4. The OpenAPI spec path (openapi-apis.yaml) has been updated to document the two new PUT endpoints.

Commits

Commit	SHA	What & Why
feat(console): update V4 APIs from import modal	c6e1ff4	Adds the Angular ApiImportV4Component dialog and wires it into the General Info page. Removes the V4 disable condition from the import button and adds two new service methods (importUpdate, importSwaggerApiUpdate) that call the new PUT endpoints.
feat(mAPI): add PUT calls to update V4 APIs	7797fcd	Adds the two new PUT REST endpoints in ApiResource.java, the UpdateApiDefinitionUseCase, the ImportDefinitionUpdateDomainService, updates the OpenAPI spec, and adds full test coverage.

Files Changed & Why

Frontend

• api-general-info.component.html — Removed api.definitionVersion === 'V4' from the import button's [disabled] condition so V4 APIs can use the import/update flow.

• • api-general-info.component.ts — Wires up the new ApiImportV4Component dialog and passes the apiId so the component knows it is in update mode.
• • api-import-v4/api-import-v4.component.ts — New component that handles the V4 import/update dialog, detects update mode from the injected apiId, and calls the appropriate service method.
• • api-import-v4/api-import-v4.component.html — Template for the V4 import dialog (file picker + format selection).
• • api-import-v4/api-import-v4.component.scss — Styles for the dialog.
• • api-import-v4/api-import-v4.component.spec.ts — Unit tests for the component.
• • api-import-v4/api-import-v4.harness.ts — Angular CDK test harness for the component.
• • application-general.module.ts — Registers ApiImportV4Component in the module.
• • api-v2.service.ts — Adds importUpdate(apiId, payload) and importSwaggerApiUpdate(apiId, descriptor) methods, both issuing PUT to /apis/{apiId}/_import/definition and /apis/{apiId}/_import/swagger respectively.
    Backend

• ApiResource.java — Adds updateApiWithDefinition() and updateApiFromSwagger() methods with PUT mappings. Both are guarded by api-definition[C] permission and delegate to UpdateApiDefinitionUseCase.

• • openapi-apis.yaml — Documents the two new PUT endpoints in the OpenAPI spec so they appear correctly in API docs and client generators.
• • UpdateApiDefinitionUseCase.java (new) — Use-case encapsulating the update logic: validates V4, fetches existing API, delegates to ImportDefinitionUpdateDomainService, returns the updated API with flows.
• • ImportDefinitionUpdateDomainService.java (new) — Domain service that orchestrates the full update: recalculates IDs, dispatches to the correct update service based on API type (PROXY/MESSAGE vs NATIVE), updates images, and upserts all sub-entities (metadata, pages, plans).
• • ImportDefinitionPageDomainService.java — Modified to support the upsert-pages flow needed during import updates.
• • ApiResource_UpdateApiWithDefinitionTest.java (new) — Integration tests covering the new PUT endpoint for definition-based updates.
• • ApiResourceTest.java — Updated to include new test cases for the update paths.
• • AbstractResourceTest.java — Base test setup updated to support the new use-case injection.
• • ResourceContextConfiguration.java — Spring context updated to wire UpdateApiDefinitionUseCase into the test context.
• • ImportDefinitionPageDomainServiceTest.java — Tests for the page upsert logic.
• • UpdateApiDefinitionUseCaseTest.java (new) — Unit tests for the use-case (V4 validation, not-found handling, happy path).
• • ProcessPromotionUseCaseTest.java —
    Updated to remain consistent with changes in ImportDefinitionUpdateDomainService.

APIM_12010_new.mov

PolicyShuffle.mov

export-import-same-no-change.mov

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement by allowing existing V4 APIs to be updated through the import mechanism. This feature provides a streamlined way to modify API configurations, whether from a Gravitee definition or an OpenAPI specification, directly within the console. The changes span both the frontend, with a dedicated user experience for V4 API updates, and the backend, with new endpoints and core logic to process these updates securely and efficiently.

Highlights

• V4 API Update Capability: Enabled the ability to update existing V4 APIs through the import process, removing the previous restriction that prevented V4 APIs from being updated via import.
• Dedicated V4 Import/Update UI: Introduced a specific UI component and dialog flow for importing and updating V4 APIs, distinguishing it from the V1/V2 API import process.
• New Backend Endpoints for V4 Updates: Added new REST API endpoints (PUT /_import/definition and PUT /_import/swagger) to handle updates of V4 APIs from Gravitee definitions and OpenAPI specifications, respectively.
• Core Logic for API Definition Updates: Implemented a new UpdateApiDefinitionUseCase in the backend to encapsulate the business logic for updating API definitions, ensuring proper validation and handling of V4 API specifics.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces the capability to update existing V4 APIs by importing new definitions, either from a Gravitee definition or an OpenAPI (Swagger) descriptor. The changes include a new Angular dialog component (ApiImportV4Component) for the update process, new API service methods (importUpdate, importSwaggerApiUpdate) in the frontend, and corresponding new PUT endpoints (/apis/{apiId}/_import/definition, /apis/{apiId}/_import/swagger) in the backend. A new UpdateApiDefinitionUseCase handles the core logic for updating API definitions, ensuring only V4 APIs are supported. The review comment highlights a code duplication issue in the newly added backend API resource, suggesting extracting a common response-building logic into a helper method for better maintainability.

[cypress]

APIM UI Tests    Run #8397

Run Properties:   Passed #8397  •  5e5deeb349: feat(e2e): add e2e test for update v4 apis using import

Project	APIM UI Tests
Branch Review	APIM-12010-enable-update-for-existing-v4-apis
Run status	Passed #8397
Run duration	07m 27s
Commit	5e5deeb349: feat(e2e): add e2e test for update v4 apis using import
Committer	vikrant
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	0
Pending	8
Skipped	0
Passing	82
View all changes introduced in this branch ↗︎

[sonarqubecloud]

Quality Gate passed for 'Gravitee.io APIM - Reporter'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud