Flatten API model: fix circular reference in REST serialization

[stalep]

Problem

The REST API added in #46 exposes a circular reference in the API model:

Node → NodeGroup → List<Node> → NodeGroup → ...

This causes StackOverflow during JSON serialization via Jackson. The current workaround in tests is using asString() to avoid RestAssured's Groovy JSON parser triggering the cycle.

The root cause is that the API records mirror the entity graph's bidirectional relationships:

record Node(..., NodeGroup group, ..., List<Node> sources)
record NodeGroup(..., Node root, List<Node> sources)
record Value(..., Node node, ...)  // affected via Node → NodeGroup cycle

Note: Folder is already flat, getGroupedValues() returns List<JsonNode>, and create() returns Long — these have no circular reference issues.

Proposed solution

Introduce flat REST DTOs with ID-based references instead of nested objects:

record NodeDto(Long id, String name, String fqdn, NodeType type, Long groupId, String operation, List<Long> sourceIds)
record NodeGroupDto(Long id, String name, Long rootId, List<Long> sourceIds)
record ValueDto(Long id, JsonNode data, Long nodeId, Long folderId, int idx)

Move JAX-RS annotations from service interfaces to dedicated REST resource classes (NodeResource, FolderResource, etc.) that wrap the services and map to DTOs. This keeps service interfaces and CLI code unchanged.

Why DTOs over Jackson annotations?

• @JsonIdentityInfo on records produces mixed JSON (first ref = full object, subsequent = bare ID) — hostile to frontend consumers
• @JsonBackReference is already on entities but cycle occurs in API records after MapStruct mapping
• @JsonView could exclude fields but then REST responses lack the relationship entirely
• Flat DTOs with groupId/sourceIds give clients the relationship without the cycle

Acceptance criteria

• REST endpoints return flat DTOs (no nested object references)
• OpenAPI spec has clean, non-recursive schemas
• No asString() workarounds needed in REST tests
• Service interfaces unchanged — CLI functionality unaffected
• All existing tests pass

[stalep]

Implementation Plan

Step 1: Create REST DTO records

New package: io.hyperfoil.tools.h5m.api.dto

record NodeDto(Long id, String name, String fqdn, NodeType type, Long groupId,
               String operation, List<Long> sourceIds) {}

record NodeGroupDto(Long id, String name, Long rootId, List<Long> sourceIds) {}

record ValueDto(Long id, JsonNode data, Long nodeId, Long folderId, int idx) {}

No FolderDto needed — Folder is already flat (record Folder(Long id, String name)).

Step 2: Add DTO mapping methods to ApiMapper

NodeDto toNodeDto(NodeEntity node);
NodeGroupDto toNodeGroupDto(NodeGroupEntity group);
ValueDto toValueDto(ValueEntity value);

MapStruct derives groupId from node.group.id, sourceIds from node.sources. No CycleAvoidingContext needed for flat DTOs.

Step 3: Create REST resource classes

Move JAX-RS annotations from service interfaces to dedicated REST resource classes. Each resource injects the service and mapper, delegates to the service, and maps to DTOs.

@Path("/api/node")
@Produces(APPLICATION_JSON)
@Tag(name = "Node")
public class NodeResource {
    @Inject NodeServiceInterface nodeService;
    @Inject ApiMapper mapper;

    @GET @Path("find")
    public List<NodeDto> findByFqdn(@QueryParam("name") String name, 
                                     @QueryParam("groupId") Long groupId) {
        // delegate to service, map to DTOs
    }
}

This keeps service interfaces unchanged — CLI code is unaffected.

Step 4: Remove JAX-RS annotations from service interfaces

REST resource classes now own the HTTP contract. Service interfaces return to being pure service contracts.

Step 5: Update REST endpoint tests

Update RestEndpointTest.java to validate flat DTO responses — no more asString() workarounds.

Files to modify

File	Change
src/main/java/.../api/dto/NodeDto.java	New — flat Node DTO
src/main/java/.../api/dto/NodeGroupDto.java	New — flat NodeGroup DTO
src/main/java/.../api/dto/ValueDto.java	New — flat Value DTO
src/main/java/.../rest/NodeResource.java	New — REST resource wrapping NodeService
src/main/java/.../rest/NodeGroupResource.java	New — REST resource wrapping NodeGroupService
src/main/java/.../rest/ValueResource.java	New — REST resource wrapping ValueService
src/main/java/.../rest/FolderResource.java	New — REST resource wrapping FolderService
src/main/java/.../entity/mapper/ApiMapper.java	Add DTO mapping methods
src/main/java/.../api/svc/*ServiceInterface.java	Remove JAX-RS annotations
src/test/java/.../rest/RestEndpointTest.java	Update assertions for flat DTO responses

Verification

1. mvn compile — no circular type references in generated OpenAPI spec
2. mvn test — all 124+ tests pass (CLI tests unchanged)
3. curl /api/node/find?name=... — returns flat JSON with groupId and sourceIds
4. curl /q/openapi — clean, non-recursive schemas
5. CLI commands work unchanged