refactor(management-api): stabilize V4, deprecate V3, promote V5 beta

Author: ndr-brt

data-protocols/data-plane-signaling/data-plane-signaling-core/src/main/java/org/eclipse/edc/signaling/port/api/DataPlaneRegistrationApiV4.java

@@ -31,7 +31,7 @@
 import static jakarta.ws.rs.HttpMethod.PUT;
 
 @OpenAPIDefinition(info = @Info(version = "v4"))
-@Tag(name = "Dataplane Signaling Registration v4beta")
+@Tag(name = "Dataplane Signaling Registration v4")
 public interface DataPlaneRegistrationApiV4 {
 
     @Operation(

data-protocols/data-plane-signaling/data-plane-signaling-core/src/main/java/org/eclipse/edc/signaling/port/api/DataPlaneRegistrationApiV4Controller.java

@@ -31,7 +31,7 @@
 import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
 import static org.eclipse.edc.web.spi.exception.ServiceResultHandler.mapToException;
 
-@Path("/v4beta/dataplanes")
+@Path("/v4/dataplanes")
 @Produces(APPLICATION_JSON)
 @Consumes(APPLICATION_JSON)
 public class DataPlaneRegistrationApiV4Controller implements DataPlaneRegistrationApiV4 {

data-protocols/data-plane-signaling/data-plane-signaling-core/src/test/java/org/eclipse/edc/signaling/DataPlaneRegistrationApiV4ControllerTest.java

@@ -121,7 +121,7 @@ protected Object controller() {
     private RequestSpecification baseRequest() {
         return given()
                 .baseUri("http://localhost:" + port)
-                .basePath("/v4beta")
+                .basePath("/v4")
                 .when();
     }
 }

data-protocols/data-plane-signaling/data-plane-signaling-core/src/test/java/org/eclipse/edc/signaling/port/api/DataPlaneRegistrationApiV4ControllerTest.java

@@ -48,7 +48,7 @@ void shouldRegisterDataPlane() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(200);
@@ -72,7 +72,7 @@ void shouldRegisterDataPlane_withAuthorizationProfile() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(200);
@@ -92,7 +92,7 @@ void shouldReturnError_whenServiceCallFails() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(409);
@@ -109,7 +109,7 @@ void shouldDeleteDataPlane() {
             given()
                     .port(port)
                     .contentType(ContentType.JSON)
-                    .delete("/v4beta/dataplanes/{dataplaneId}", "dp-id")
+                    .delete("/v4/dataplanes/{dataplaneId}", "dp-id")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(200);
@@ -124,7 +124,7 @@ void shouldReturnNotFound_whenDataPlaneDoesNotExist() {
             given()
                     .port(port)
                     .contentType(ContentType.JSON)
-                    .delete("/v4beta/dataplanes/{dataplaneId}", "dp-id")
+                    .delete("/v4/dataplanes/{dataplaneId}", "dp-id")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(404);

data-protocols/data-plane-signaling/src/main/resources/signaling-api-version.json

@@ -2,6 +2,6 @@
   {
     "version": "1.0.0-alpha",
     "urlPath": "/v1",
-    "lastUpdated": "2026-04-13T14:00:01Z"
+    "lastUpdated": "2026-04-15T14:00:01Z"
   }
 ]

extensions/common/api/management-api-configuration/src/main/java/org/eclipse/edc/connector/api/management/configuration/ManagementApiConfigurationExtension.java

@@ -15,6 +15,8 @@
 package org.eclipse.edc.connector.api.management.configuration;
 
 import jakarta.json.Json;
+import jakarta.ws.rs.container.ContainerRequestContext;
+import jakarta.ws.rs.container.ContainerRequestFilter;
 import org.eclipse.edc.connector.controlplane.transform.edc.contractagreement.from.JsonObjectFromContractAgreementTransformer;
 import org.eclipse.edc.connector.controlplane.transform.edc.from.JsonObjectFromAssetTransformer;
 import org.eclipse.edc.connector.controlplane.transform.edc.from.JsonObjectFromDataplaneMetadataTransformer;
@@ -31,6 +33,7 @@
 import org.eclipse.edc.runtime.metamodel.annotation.Setting;
 import org.eclipse.edc.runtime.metamodel.annotation.Settings;
 import org.eclipse.edc.spi.EdcException;
+import org.eclipse.edc.spi.monitor.Monitor;
 import org.eclipse.edc.spi.query.CriterionOperatorRegistry;
 import org.eclipse.edc.spi.system.Hostname;
 import org.eclipse.edc.spi.system.ServiceExtension;
@@ -134,6 +137,7 @@ public void initialize(ServiceExtensionContext context) {
         jsonLd.registerContext(EDC_CONNECTOR_MANAGEMENT_CONTEXT_V2, MANAGEMENT_SCOPE_V4);
 
         webService.registerResource(ApiContext.MANAGEMENT, new ObjectMapperProvider(typeManager, JSON_LD));
+        webService.registerResource(ApiContext.MANAGEMENT, new DeprecatedVersionLog(context.getMonitor()));
 
         var managementApiTransformerRegistry = transformerRegistry.forContext(MANAGEMENT_API_CONTEXT);
 
@@ -189,4 +193,20 @@ record ManagementApiConfiguration(
     ) {
 
     }
+
+    @Deprecated(since = "management-api:v3")
+    private static class DeprecatedVersionLog implements ContainerRequestFilter {
+        private final Monitor monitor;
+
+        DeprecatedVersionLog(Monitor monitor) {
+            this.monitor = monitor;
+        }
+
+        @Override
+        public void filter(ContainerRequestContext requestContext) {
+            if (requestContext.getUriInfo().getPath().startsWith("v3/")) {
+                monitor.warning("Management API V3 has been deprecated, please switch to V4 as V3 will be removed in the upcoming versions");
+            }
+        }
+    }
 }

extensions/common/api/management-api-configuration/src/main/resources/management-api-version.json

@@ -3,18 +3,18 @@
     "version": "3.1.6",
     "urlPath": "/v3",
     "lastUpdated": "2026-03-12T08:30:01Z",
-    "maturity": "stable"
+    "maturity": "deprecated"
   },
   {
-    "version": "4.0.0-beta",
-    "urlPath": "/v4beta",
+    "version": "4.0.0",
+    "urlPath": "/v4",
     "lastUpdated": "2026-04-09T09:43:01Z",
-    "maturity": "beta"
+    "maturity": "stable"
   },
   {
-    "version": "5.0.0-alpha",
-    "urlPath": "/v5alpha",
+    "version": "5.0.0-beta",
+    "urlPath": "/v5beta",
     "lastUpdated": "2026-03-27T09:00:00Z",
-    "maturity": "alpha"
+    "maturity": "beta"
   }
 ]

extensions/control-plane/api/management-api-v5/asset-api-v5/src/main/java/org/eclipse/edc/connector/controlplane/api/management/asset/v5/AssetApiV5.java

@@ -31,8 +31,8 @@
 
 @OpenAPIDefinition(
         info = @Info(description = "This contains both the current and the new Asset API, which accepts JSON-LD and will " +
-                "become the standard API once the Dataspace Protocol is stable.", title = "Asset API", version = "v5alpha"))
-@Tag(name = "Asset v5alpha")
+                "become the standard API once the Dataspace Protocol is stable.", title = "Asset API", version = "v5beta"))
+@Tag(name = "Asset v5beta")
 public interface AssetApiV5 {
     @Operation(description = "Creates a new asset together with a data address",
             requestBody = @RequestBody(content = @Content(schema = @Schema(ref = ManagementApiJsonSchema.V4.ASSET))),

extensions/control-plane/api/management-api-v5/asset-api-v5/src/main/java/org/eclipse/edc/connector/controlplane/api/management/asset/v5/AssetApiV5Controller.java

@@ -58,7 +58,7 @@
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
-@Path("/v5alpha/participants/{participantContextId}/assets")
+@Path("/v5beta/participants/{participantContextId}/assets")
 public class AssetApiV5Controller implements AssetApiV5 {
     private final TypeTransformerRegistry typeTransformerRegistry;
     private final AssetService assetService;

extensions/control-plane/api/management-api-v5/asset-api-v5/src/test/java/org/eclipse/edc/connector/controlplane/api/management/asset/v5/AssetApiV5ControllerTest.java

@@ -19,7 +19,7 @@
 public class AssetApiV5ControllerTest extends AssetApiControllerTest {
     @Override
     protected String versionPath() {
-        return "v5alpha";
+        return "v5beta";
     }
 
     @Override