Instruction file imported from dream-horizon-org/odin-scout-ent (.cursor/rules/api-endpoint-patterns.mdc). Copyright stays with the author.

API Endpoint Patterns

Controller Structure

@RestController
@RequestMapping("/resource-name")
public class ResourceController {

    private final SomeService someService;

    public ResourceController(SomeService someService) {
        this.someService = someService;
    }

    @PostMapping("/action")
    public ResponseEntity<ActionResponse> action(@Valid @RequestBody ActionRequest request) {
        var result = someService.doAction(request.field1(), request.field2());
        return ResponseEntity.ok(new ActionResponse(result));
    }
}

DTO Records

// Request — use validation annotations
public record ActionRequest(
        @NotBlank(message = "field1 is required")
        String field1,
        @Pattern(regexp = ValidationPatterns.SOME_REGEXP, message = ValidationPatterns.SOME_MESSAGE)
        String field2
) {}

// Response — thin wrapper around domain result
public record ActionResponse(List<SomeDomainModel> items) {}

Key Patterns

• Controllers are thin: map DTO → call service → wrap in response
• Always return ResponseEntity.ok(...) for success
• Group related DTOs in sub-packages: dto/network/, dto/kubernetes/, etc.
• Use base request records for shared fields (e.g. NetworkBaseRequest)
• Shared validation regex goes in ValidationPatterns