feat: add v3.1.0-alpha of the Managemenet API (#4343)

* feat(api): add /v3.1alpha of the Management API

* pr remarks

* add maturity field

core/common/lib/boot-lib/src/test/java/org/eclipse/edc/boot/apiversion/ApiVersionServiceImplTest.java

@@ -26,23 +26,23 @@ class ApiVersionServiceImplTest {
 
     @Test
     void addRecord_whenNotExists() {
-        service.addRecord("foo", new VersionRecord("1.0.0", "/v1/", Instant.now()));
+        service.addRecord("foo", new VersionRecord("1.0.0", "/v1/", Instant.now(), "stable"));
         assertThat(service.getRecords()).hasSize(1).containsKey("foo");
         assertThat(service.getRecords().get("foo")).hasSize(1);
     }
 
     @Test
     void addRecord_whenExists() {
-        service.addRecord("foo", new VersionRecord("1.0.0", "/v1/", Instant.now()));
-        service.addRecord("foo", new VersionRecord("2.0.0", "/v2/", Instant.now()));
+        service.addRecord("foo", new VersionRecord("1.0.0", "/v1/", Instant.now(), "stable"));
+        service.addRecord("foo", new VersionRecord("2.0.0", "/v2/", Instant.now(), "stable"));
         assertThat(service.getRecords()).hasSize(1).containsKey("foo");
         assertThat(service.getRecords().get("foo")).hasSize(2);
     }
 
     @Test
     void getRecords() {
-        service.addRecord("foo1", new VersionRecord("1.0.0", "/v1/", Instant.now()));
-        service.addRecord("foo2", new VersionRecord("2.0.0", "/v2/", Instant.now()));
+        service.addRecord("foo1", new VersionRecord("1.0.0", "/v1/", Instant.now(), "stable"));
+        service.addRecord("foo2", new VersionRecord("2.0.0", "/v2/", Instant.now(), "stable"));
         assertThat(service.getRecords()).hasSize(2);
     }
 }

extensions/common/api/api-observability/src/main/java/org/eclipse/edc/api/observability/ObservabilityApiExtension.java

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.api.observability;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import org.eclipse.edc.runtime.metamodel.annotation.Extension;
 import org.eclipse.edc.runtime.metamodel.annotation.Inject;
 import org.eclipse.edc.spi.EdcException;
@@ -27,13 +28,14 @@
 import org.eclipse.edc.web.spi.WebService;
 
 import java.io.IOException;
+import java.util.stream.Stream;
 
 @Extension(value = ObservabilityApiExtension.NAME)
 public class ObservabilityApiExtension implements ServiceExtension {
 
     public static final String NAME = "Observability API";
     public static final String OBSERVABILITY_CONTEXT = "observability";
-    private static final String API_VERSION_JSON_FILE = "version.json";
+    private static final String API_VERSION_JSON_FILE = "observability-api-version.json";
     private final HealthCheckResult result = HealthCheckResult.Builder.newInstance().component(NAME).build();
 
     @Inject
@@ -66,8 +68,10 @@ private void registerVersionInfo(ClassLoader resourceClassLoader) {
             if (versionContent == null) {
                 throw new EdcException("Version file not found or not readable.");
             }
-            var content = typeManager.getMapper().readValue(versionContent, VersionRecord.class);
-            apiVersionService.addRecord(OBSERVABILITY_CONTEXT, content);
+            Stream.of(typeManager.getMapper()
+                            .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                            .readValue(versionContent, VersionRecord[].class))
+                    .forEach(vr -> apiVersionService.addRecord(OBSERVABILITY_CONTEXT, vr));
         } catch (IOException e) {
             throw new EdcException(e);
         }

extensions/common/api/api-observability/src/main/resources/observability-api-version.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "1.0.0",
+    "urlPath": "/v1",
+    "lastUpdated": "2024-05-21T09:12:44Z",
+    "maturity": "stable"
+  }
+]

extensions/common/api/control-api-configuration/src/main/java/org/eclipse/edc/connector/api/control/configuration/ControlApiConfigurationExtension.java

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.connector.api.control.configuration;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import org.eclipse.edc.api.auth.spi.AuthenticationRequestFilter;
 import org.eclipse.edc.api.auth.spi.registry.ApiAuthenticationRegistry;
 import org.eclipse.edc.jsonld.spi.JsonLd;
@@ -41,6 +42,7 @@
 
 import java.io.IOException;
 import java.net.URI;
+import java.util.stream.Stream;
 
 import static java.lang.String.format;
 import static org.eclipse.edc.jsonld.spi.Namespaces.DSPACE_PREFIX;
@@ -76,7 +78,7 @@ public class ControlApiConfigurationExtension implements ServiceExtension {
             .name(WEB_SERVICE_NAME)
             .build();
     private static final String CONTROL_SCOPE = "CONTROL_API";
-    private static final String API_VERSION_JSON_FILE = "version.json";
+    private static final String API_VERSION_JSON_FILE = "control-api-version.json";
 
     @Inject
     private WebServer webServer;
@@ -124,8 +126,10 @@ private void registerVersionInfo(ClassLoader resourceClassLoader) {
             if (versionContent == null) {
                 throw new EdcException("Version file not found or not readable.");
             }
-            var content = typeManager.getMapper().readValue(versionContent, VersionRecord.class);
-            apiVersionService.addRecord(ApiContext.CONTROL, content);
+            Stream.of(typeManager.getMapper()
+                            .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                            .readValue(versionContent, VersionRecord[].class))
+                    .forEach(vr -> apiVersionService.addRecord(ApiContext.CONTROL, vr));
         } catch (IOException e) {
             throw new EdcException(e);
         }

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

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "1.0.1",
+    "urlPath": "/v1",
+    "lastUpdated": "2024-06-02T14:30:00Z",
+    "maturity": "stable"
+  }
+]

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

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.connector.api.management.configuration;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import jakarta.json.Json;
 import org.eclipse.edc.api.auth.spi.AuthenticationRequestFilter;
 import org.eclipse.edc.api.auth.spi.registry.ApiAuthenticationRegistry;
@@ -57,6 +58,7 @@
 import java.io.IOException;
 import java.net.URI;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import static java.lang.String.format;
 import static org.eclipse.edc.policy.model.OdrlNamespace.ODRL_PREFIX;
@@ -70,7 +72,7 @@
 @Extension(ManagementApiConfigurationExtension.NAME)
 public class ManagementApiConfigurationExtension implements ServiceExtension {
 
-    public static final String API_VERSION_JSON_FILE = "version.json";
+    public static final String API_VERSION_JSON_FILE = "management-api-version.json";
     public static final String NAME = "Management API configuration";
     public static final String WEB_SERVICE_NAME = "Management API";
 
@@ -157,8 +159,10 @@ private void registerVersionInfo(ClassLoader resourceClassLoader) {
             if (versionContent == null) {
                 throw new EdcException("Version file not found or not readable.");
             }
-            var content = typeManager.getMapper().readValue(versionContent, VersionRecord.class);
-            apiVersionService.addRecord(ApiContext.MANAGEMENT, content);
+            Stream.of(typeManager.getMapper()
+                            .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                            .readValue(versionContent, VersionRecord[].class))
+                    .forEach(vr -> apiVersionService.addRecord(ApiContext.MANAGEMENT, vr));
         } catch (IOException e) {
             throw new EdcException(e);
         }

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

@@ -0,0 +1,14 @@
+[
+  {
+    "version": "3.0.1",
+    "urlPath": "/v3",
+    "lastUpdated": "2024-06-13T14:28:00Z",
+    "maturity": "stable"
+  },
+  {
+    "version": "3.1.0-alpha",
+    "urlPath": "/v3.1alpha",
+    "lastUpdated": "2024-07-09T09:17:00Z",
+    "maturity": "alpha"
+  }
+]

extensions/common/api/version-api/src/main/java/org/eclipse/edc/connector/api/management/version/VersionApiExtension.java

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.connector.api.management.version;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import org.eclipse.edc.connector.api.management.version.v1.VersionApiController;
 import org.eclipse.edc.runtime.metamodel.annotation.Extension;
 import org.eclipse.edc.runtime.metamodel.annotation.Inject;
@@ -31,6 +32,7 @@
 import org.eclipse.edc.web.spi.configuration.WebServiceSettings;
 
 import java.io.IOException;
+import java.util.stream.Stream;
 
 @Extension(value = VersionApiExtension.NAME)
 public class VersionApiExtension implements ServiceExtension {
@@ -50,7 +52,7 @@ public class VersionApiExtension implements ServiceExtension {
             .name(WEB_SERVICE_NAME)
             .build();
 
-    private static final String API_VERSION_JSON_FILE = "version.json";
+    private static final String API_VERSION_JSON_FILE = "version-api-version.json";
     @Inject
     private WebService webService;
 
@@ -83,8 +85,10 @@ private void registerVersionInfo(ClassLoader resourceClassLoader) {
             if (versionContent == null) {
                 throw new EdcException("Version file not found or not readable.");
             }
-            var content = typeManager.getMapper().readValue(versionContent, VersionRecord.class);
-            apiVersionService.addRecord(ApiContext.VERSION, content);
+            Stream.of(typeManager.getMapper()
+                            .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                            .readValue(versionContent, VersionRecord[].class))
+                    .forEach(vr -> apiVersionService.addRecord(ApiContext.VERSION, vr));
         } catch (IOException e) {
             throw new EdcException(e);
         }

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

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "1.0.0",
+    "urlPath": "/v1",
+    "lastUpdated": "2024-05-21T09:12:44Z",
+    "maturity": "stable"
+  }
+]

extensions/common/api/version-api/src/test/java/org/eclipse/edc/connector/api/management/version/VersionApiControllerTest.java

@@ -45,7 +45,7 @@ void setup() {
 
     @Test
     void getVersion() {
-        when(apiServiceMock.getRecords()).thenReturn(Map.of("test-api", List.of(new VersionRecord("1.0.0", "/v1", Instant.now()))));
+        when(apiServiceMock.getRecords()).thenReturn(Map.of("test-api", List.of(new VersionRecord("1.0.0", "/v1", Instant.now(), "deprecated"))));
         var result = baseRequest()
                 .get("/v1/version")
                 .then()

extensions/common/iam/identity-trust/identity-trust-sts/identity-trust-sts-api/src/main/java/org/eclipse/edc/api/iam/identitytrust/sts/StsApiConfigurationExtension.java

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.api.iam.identitytrust.sts;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import org.eclipse.edc.runtime.metamodel.annotation.Extension;
 import org.eclipse.edc.runtime.metamodel.annotation.Inject;
 import org.eclipse.edc.runtime.metamodel.annotation.SettingContext;
@@ -29,6 +30,7 @@
 import org.eclipse.edc.web.spi.configuration.WebServiceSettings;
 
 import java.io.IOException;
+import java.util.stream.Stream;
 
 @Extension(value = StsApiConfigurationExtension.NAME)
 public class StsApiConfigurationExtension implements ServiceExtension {
@@ -49,7 +51,7 @@ public class StsApiConfigurationExtension implements ServiceExtension {
             .useDefaultContext(false)
             .name(WEB_SERVICE_NAME)
             .build();
-    private static final String API_VERSION_JSON_FILE = "version.json";
+    private static final String API_VERSION_JSON_FILE = "sts-api-version.json";
 
     @Inject
     private WebServer webServer;
@@ -77,8 +79,10 @@ private void registerVersionInfo(ClassLoader resourceClassLoader) {
             if (versionContent == null) {
                 throw new EdcException("Version file not found or not readable.");
             }
-            var content = typeManager.getMapper().readValue(versionContent, VersionRecord.class);
-            apiVersionService.addRecord(ApiContext.STS, content);
+            Stream.of(typeManager.getMapper()
+                            .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                            .readValue(versionContent, VersionRecord[].class))
+                    .forEach(vr -> apiVersionService.addRecord(ApiContext.STS, vr));
         } catch (IOException e) {
             throw new EdcException(e);
         }

extensions/common/iam/identity-trust/identity-trust-sts/identity-trust-sts-api/src/main/resources/sts-api-version.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "1.0.0",
+    "urlPath": "/v1",
+    "lastUpdated": "2024-05-21T09:12:44Z",
+    "maturity": "stable"
+  }
+]

resources/openapi/README.md

@@ -1,5 +1,6 @@
 # Openapi
 
 ### .version files
-The `*.version` files contain the path for the `version.json` file that will be used by the openapi publish workflow to
-get the context api version to be published to github pages.
+
+The `*.version` files contain the path for the `*-version.json` file that will be used by the openapi publish workflow
+to get the context api version to be published to github pages.

resources/openapi/control-api.version

@@ -1 +1 @@
-extensions/common/api/control-api-configuration/src/main/resources/version.json
+extensions/common/api/control-api-configuration/src/main/resources/control-api-version.json

resources/openapi/management-api.version

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

resources/openapi/observability-api.version

@@ -1 +1 @@
-extensions/common/api/api-observability/src/main/resources/version.json
+extensions/common/api/api-observability/src/main/resources/observability-api-version.json

resources/openapi/sts-api.version

@@ -1 +1 @@
-extensions/common/iam/identity-trust/identity-trust-sts/identity-trust-sts-api/src/main/resources/version.json
+extensions/common/iam/identity-trust/identity-trust-sts/identity-trust-sts-api/src/main/resources/sts-api-version.json

resources/openapi/version-api.version

@@ -1 +1 @@
-extensions/common/api/version-api/src/main/resources/version.json
+extensions/common/api/version-api/src/main/resources/version-api-version.json

spi/common/boot-spi/src/main/java/org/eclipse/edc/spi/system/apiversion/VersionRecord.java

@@ -22,6 +22,7 @@
  * @param version     The full version as SemVer string
  * @param urlPath     The path element, e.g. /v3
  * @param lastUpdated When the API's version was last bumped
+ * @param maturity    Maturity level of an API, can be "stable", "deprecated", "alpha" or "beta"
  */
-public record VersionRecord(String version, String urlPath, Instant lastUpdated) {
+public record VersionRecord(String version, String urlPath, Instant lastUpdated, String maturity) {
 }

system-tests/version-api/version-api-test-runner/build.gradle.kts

@@ -35,7 +35,6 @@ dependencies {
     //we need the JacksonJsonLd util class
     testImplementation(project(":core:common:lib:json-ld-lib"))
     testImplementation(project(":extensions:common:json-ld"))
-    testImplementation(project(":extensions:common:api:control-api-configuration"))
 
     testImplementation(libs.restAssured)
     testImplementation(libs.assertj)

system-tests/version-api/version-api-test-runner/src/test/java/org/eclipse/edc/test/e2e/versionapi/Runtimes.java

@@ -17,7 +17,9 @@
 import org.eclipse.edc.connector.dataplane.spi.manager.DataPlaneManager;
 import org.eclipse.edc.iam.identitytrust.sts.spi.service.StsClientService;
 import org.eclipse.edc.iam.identitytrust.sts.spi.service.StsClientTokenGeneratorService;
-import org.eclipse.edc.junit.extensions.EdcRuntimeExtension;
+import org.eclipse.edc.junit.extensions.EmbeddedRuntime;
+import org.eclipse.edc.junit.extensions.RuntimeExtension;
+import org.eclipse.edc.junit.extensions.RuntimePerClassExtension;
 import org.eclipse.edc.sql.testfixtures.PostgresqlEndToEndInstance;
 import org.jetbrains.annotations.NotNull;
 
@@ -28,12 +30,8 @@
 
 public interface Runtimes {
 
-    static EdcRuntimeExtension inMemoryRuntime() {
-        var rt = new EdcRuntimeExtension(
-                "control-plane",
-                inMemoryConfiguration(),
-                ":system-tests:version-api:version-api-test-runtime"
-        );
+    static RuntimeExtension inMemoryRuntime() {
+        var rt = new RuntimePerClassExtension(new EmbeddedRuntime("control-plane", inMemoryConfiguration(), ":system-tests:version-api:version-api-test-runtime"));
         rt.registerServiceMock(DataPlaneManager.class, mock());
         rt.registerServiceMock(StsClientService.class, mock());
         rt.registerServiceMock(StsClientTokenGeneratorService.class, mock());