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

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

@@ -32,7 +32,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/port/api/DataPlaneRegistrationApiV4ControllerTest.java

@@ -58,7 +58,7 @@ void shouldRegisterDataPlane() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(200);
@@ -82,7 +82,7 @@ void shouldRegisterDataPlane_withAuthorizationProfile() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(200);
@@ -102,7 +102,7 @@ void shouldReturnError_whenServiceCallFails() {
                     .port(port)
                     .contentType(ContentType.JSON)
                     .body(message)
-                    .put("/v4beta/dataplanes")
+                    .put("/v4/dataplanes")
                     .then()
                     .log().ifValidationFails()
                     .statusCode(409);
@@ -119,7 +119,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);
@@ -134,7 +134,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-15T14:00:01Z"
+    "lastUpdated": "2026-04-16T14: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

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

@@ -28,8 +28,8 @@
 import jakarta.ws.rs.core.SecurityContext;
 import org.eclipse.edc.api.management.schema.ManagementApiJsonSchema;
 
-@OpenAPIDefinition(info = @Info(version = "v5alpha"))
-@Tag(name = "Catalog v5alpha")
+@OpenAPIDefinition(info = @Info(version = "v5beta"))
+@Tag(name = "Catalog v5beta")
 public interface CatalogApiV5 {
 
     @Operation(

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

@@ -47,7 +47,7 @@
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
-@Path("/v5alpha/participants/{participantContextId}/catalog")
+@Path("/v5beta/participants/{participantContextId}/catalog")
 public class CatalogApiV5Controller implements CatalogApiV5 {
     private final AuthorizationService authorizationService;
     private final CatalogService service;

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

@@ -23,7 +23,7 @@ class CatalogApiV5ControllerTest extends BaseCatalogApiControllerTest {
 
     @Override
     protected String baseUrl(String participantContextId) {
-        return "/v5alpha/participants/%s/catalog".formatted(participantContextId);
+        return "/v5beta/participants/%s/catalog".formatted(participantContextId);
     }
 
     @Override

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

@@ -27,8 +27,8 @@
 import jakarta.json.JsonObject;
 import org.eclipse.edc.api.management.schema.ManagementApiJsonSchema;
 
-@OpenAPIDefinition(info = @Info(title = "Cel Expressions Management API", version = "v5alpha"))
-@Tag(name = "Cel Expressions v5alpha")
+@OpenAPIDefinition(info = @Info(title = "Cel Expressions Management API", version = "v5beta"))
+@Tag(name = "Cel Expressions v5beta")
 public interface CelExpressionApiV5 {
 
     @Operation(description = "Create a Cel Expression.",

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

@@ -47,7 +47,7 @@
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
-@Path("/v5alpha/celexpressions")
+@Path("/v5beta/celexpressions")
 public class CelExpressionApiV5Controller implements CelExpressionApiV5 {
 
     private final CelPolicyExpressionService service;

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

@@ -20,7 +20,7 @@
 public class CelExpressionApiV5ControllerTest extends CelExpressionApiControllerTestBase {
     @Override
     protected String versionPath() {
-        return "v5alpha";
+        return "v5beta";
     }
 
     @Override

extensions/control-plane/api/management-api-v5/contract-agreement-api-v5/src/main/java/org/eclipse/edc/connector/controlplane/api/management/contractagreement/v5/ContractAgreementApiV5.java

@@ -28,8 +28,8 @@
 import jakarta.ws.rs.core.SecurityContext;
 import org.eclipse.edc.api.management.schema.ManagementApiJsonSchema;
 
-@OpenAPIDefinition(info = @Info(version = "v5alpha"))
-@Tag(name = "Contract Agreement v5alpha")
+@OpenAPIDefinition(info = @Info(version = "v5beta"))
+@Tag(name = "Contract Agreement v5beta")
 public interface ContractAgreementApiV5 {
 
     @Operation(description = "Gets all contract agreements according to a particular query",

extensions/control-plane/api/management-api-v5/contract-agreement-api-v5/src/main/java/org/eclipse/edc/connector/controlplane/api/management/contractagreement/v5/ContractAgreementApiV5Controller.java

@@ -40,7 +40,7 @@
 
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
-@Path("/v5alpha/participants/{participantContextId}/contractagreements")
+@Path("/v5beta/participants/{participantContextId}/contractagreements")
 public class ContractAgreementApiV5Controller extends BaseContractAgreementApiV5Controller implements ContractAgreementApiV5 {
     public ContractAgreementApiV5Controller(ContractAgreementService service, AuthorizationService authorizationService, TypeTransformerRegistry transformerRegistry, Monitor monitor, JsonObjectValidatorRegistry validatorRegistry) {
         super(service, authorizationService, transformerRegistry, monitor, validatorRegistry);

extensions/control-plane/api/management-api-v5/contract-agreement-api-v5/src/test/java/org/eclipse/edc/connector/controlplane/api/management/contractagreement/v5/ContractAgreementApiV5ControllerTest.java

@@ -24,6 +24,6 @@ protected Object controller() {
 
     @Override
     protected String versionPath() {
-        return "v5alpha";
+        return "v5beta";
     }
 }