From 370125eb9471e8a7f7d0076f38af7754675f372f Mon Sep 17 00:00:00 2001
From: Lucio Lelii <lucio.lelii@isti.cnr.it>
Date: Wed, 2 Sep 2026 09:56:26 +0200
Subject: [PATCH] deprecate(api): mark legacy /blocks/types/catalog in favor of
 /blocks/types/configurations/catalog

Both endpoints returned the identical compact block catalog payload;
/types/configurations/catalog was already documented as "Alias of
/blocks/types/catalog" and follows the naming used by the other
configurations/* endpoints (descriptors, {type}/configuration/descriptor).

Frontend has migrated to /blocks/types/configurations/catalog, so:
- getTypeCatalog() (@GetMapping /types/catalog) is now @Deprecated
  (forRemoval, since 2026-09) and delegates to getConfigurationCatalog()
- getConfigurationCatalog() (@GetMapping /types/configurations/catalog)
  now holds the real implementation instead of delegating to the
  deprecated method

Verified with `mvn test`: 462 tests, 0 failures, 0 errors.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .../manager/controllers/BlocksController.java | 30 +++++++++++--------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/src/main/java/it/cnr/isti/workflow/manager/controllers/BlocksController.java b/src/main/java/it/cnr/isti/workflow/manager/controllers/BlocksController.java
index d52a9f6..d684950 100644
--- a/src/main/java/it/cnr/isti/workflow/manager/controllers/BlocksController.java
+++ b/src/main/java/it/cnr/isti/workflow/manager/controllers/BlocksController.java
@@ -83,9 +83,25 @@ public class BlocksController {
         return blockTypes.values().stream().map(this::toDescriptor).toList();
     }
 
+    /**
+     * @deprecated use {@link #getConfigurationCatalog()} ({@code /blocks/types/configurations/catalog}) instead.
+     */
+    @Deprecated(forRemoval = true, since = "2026-09")
     @GetMapping("/types/catalog")
-    @Operation(summary = "Get compact block type catalog", description = "Returns all block types with JSON schemas compacted through shared schema definitions.")
+    @Operation(summary = "Get compact block type catalog", description = "Deprecated: use /blocks/types/configurations/catalog instead. Returns all block types with JSON schemas compacted through shared schema definitions.", deprecated = true)
     public BlockConfigurationCatalog getTypeCatalog() {
+        return getConfigurationCatalog();
+    }
+
+    @GetMapping("/types/configurations/descriptors")
+    @Operation(summary = "Get block configuration descriptors", description = "Returns one descriptor for each block type, including JSON schema.")
+    public List<BlockConfigurationDescriptor> getConfigurationDescriptors() {
+        return getTypes();
+    }
+
+    @GetMapping("/types/configurations/catalog")
+    @Operation(summary = "Get compact block configuration descriptors", description = "Returns one compact descriptor for each block type, with shared schema definitions lifted to the response root.")
+    public BlockConfigurationCatalog getConfigurationCatalog() {
         List<BlockConfigurationDescriptor> descriptors = getTypes();
         JsonSchemaCatalogBundler.SchemaBundle bundle = schemaCatalogBundler.bundle(descriptors.stream()
                 .map(BlockConfigurationDescriptor::schema)
@@ -99,18 +115,6 @@ public class BlocksController {
         return new BlockConfigurationCatalog(bundle.sharedDefinitions(), compactDescriptors);
     }
 
-    @GetMapping("/types/configurations/descriptors")
-    @Operation(summary = "Get block configuration descriptors", description = "Returns one descriptor for each block type, including JSON schema.")
-    public List<BlockConfigurationDescriptor> getConfigurationDescriptors() {
-        return getTypes();
-    }
-
-    @GetMapping("/types/configurations/catalog")
-    @Operation(summary = "Get compact block configuration descriptors", description = "Alias of /blocks/types/catalog. Returns one compact descriptor for each block type, with shared schema definitions lifted to the response root.")
-    public BlockConfigurationCatalog getConfigurationCatalog() {
-        return getTypeCatalog();
-    }
-
     @GetMapping("/types/{type}/configuration/descriptor")
     @Operation(summary = "Get block configuration descriptor by type", description = "Returns the descriptor and JSON schema for the requested block type.")
     public BlockConfigurationDescriptor getConfigurationDescriptorForType(@PathVariable String type) {