Feature/cda 99 catalog ts extents versioned improvements

cwms-data-api/src/main/java/cwms/cda/ApiServlet.java

@@ -91,6 +91,7 @@
 import cwms.cda.api.TimeSeriesController;
 import cwms.cda.api.TimeSeriesFilteredController;
 import cwms.cda.api.TimeSeriesGroupController;
+import cwms.cda.api.TimeSeriesVersionsController;
 import cwms.cda.api.TimeSeriesIdentifierDescriptorController;
 import cwms.cda.api.TimeSeriesRecentController;
 import cwms.cda.api.TimeZoneController;
@@ -500,6 +501,10 @@ protected void configureRoutes() {
         get(recentPath, new TimeSeriesRecentController(metrics));
         addCacheControl(recentPath, 5, TimeUnit.MINUTES);
 
+        String versionsPath = "/timeseries/versions/";
+        get(versionsPath, new TimeSeriesVersionsController(metrics));
+        addCacheControl(versionsPath, 5, TimeUnit.MINUTES);
+
         String filteredPath = "/timeseries/filtered";
         get(filteredPath, new TimeSeriesFilteredController(metrics));
         addCacheControl(filteredPath, 5, TimeUnit.MINUTES);

cwms-data-api/src/main/java/cwms/cda/api/TimeSeriesVersionsController.java

@@ -0,0 +1,120 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 Hydrologic Engineering Center
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package cwms.cda.api;
+
+import static cwms.cda.api.Controllers.BEGIN;
+import static cwms.cda.api.Controllers.END;
+import static cwms.cda.api.Controllers.NAME;
+import static cwms.cda.api.Controllers.OFFICE;
+import static cwms.cda.api.Controllers.PAGE;
+import static cwms.cda.api.Controllers.PAGE_SIZE;
+import static cwms.cda.api.Controllers.RESULTS;
+import static cwms.cda.api.Controllers.SIZE;
+import static cwms.cda.api.Controllers.STATUS_200;
+import static cwms.cda.api.Controllers.TIMEZONE;
+import static cwms.cda.data.dao.JooqDao.getDslContext;
+
+import com.codahale.metrics.Histogram;
+import com.codahale.metrics.MetricRegistry;
+import com.codahale.metrics.Timer;
+import cwms.cda.data.dao.TimeSeriesDao;
+import cwms.cda.data.dao.TimeSeriesDaoImpl;
+import cwms.cda.data.dto.TimeSeriesVersions;
+import cwms.cda.formatters.ContentType;
+import cwms.cda.formatters.Formats;
+import io.javalin.core.util.Header;
+import io.javalin.http.Context;
+import io.javalin.http.Handler;
+import io.javalin.plugin.openapi.annotations.OpenApi;
+import io.javalin.plugin.openapi.annotations.OpenApiContent;
+import io.javalin.plugin.openapi.annotations.OpenApiParam;
+import io.javalin.plugin.openapi.annotations.OpenApiResponse;
+import java.time.ZonedDateTime;
+import javax.servlet.http.HttpServletResponse;
+import org.jetbrains.annotations.NotNull;
+import org.jooq.DSLContext;
+
+public final class TimeSeriesVersionsController implements Handler {
+    private final MetricRegistry metrics;
+    private final Histogram requestResultSize;
+    private final String className = this.getClass().getName();
+
+    public TimeSeriesVersionsController(MetricRegistry metrics) {
+        this.metrics = metrics;
+        requestResultSize = this.metrics.histogram(MetricRegistry.name(className, RESULTS, SIZE));
+    }
+
+    protected TimeSeriesDao getTimeSeriesDao(DSLContext dsl) {
+        return new TimeSeriesDaoImpl(dsl, metrics);
+    }
+
+    @OpenApi(
+            description = "Returns TimeSeries versions and their extents for a given TimeSeries identifier",
+            queryParams = {
+                    @OpenApiParam(name = NAME, required = true, description = "The TimeSeries identifier"),
+                    @OpenApiParam(name = OFFICE, description = "The office identifier"),
+                    @OpenApiParam(name = BEGIN, description = "The start of the time window to filter versions"),
+                    @OpenApiParam(name = END, description = "The end of the time window to filter versions"),
+                    @OpenApiParam(name = TIMEZONE, description = "The timezone for the begin and end parameters (default is UTC)"),
+                    @OpenApiParam(name = PAGE, description = "The cursor to the current page of data"),
+                    @OpenApiParam(name = PAGE_SIZE, type = Integer.class, description = "The number of records fetched per-page")
+            },
+            responses = {
+                    @OpenApiResponse(status = STATUS_200, content = {
+                            @OpenApiContent(type = Formats.JSONV1, from = TimeSeriesVersions.class)
+                    })
+            },
+            tags = {TimeSeriesController.TAG}
+    )
+    @Override
+    public void handle(@NotNull Context ctx) throws Exception {
+        try (Timer.Context ignored = Controllers.markAndTime(metrics, className, "getTimeSeriesVersions")) {
+            DSLContext dsl = getDslContext(ctx);
+            TimeSeriesDao dao = getTimeSeriesDao(dsl);
+
+            String tsId = ctx.queryParam(NAME);
+            String office = ctx.queryParam(OFFICE);
+            String beginStr = ctx.queryParam(BEGIN);
+            String endStr = ctx.queryParam(END);
+            String timezone = ctx.queryParamAsClass(TIMEZONE, String.class).getOrDefault("UTC");
+            String cursor = ctx.queryParam(PAGE);
+            int pageSize = ctx.queryParamAsClass(PAGE_SIZE, Integer.class).getOrDefault(100);
+
+            ZonedDateTime begin = beginStr != null ? Controllers.queryParamAsZdt(ctx, BEGIN, timezone) : null;
+            ZonedDateTime end = endStr != null ? Controllers.queryParamAsZdt(ctx, END, timezone) : null;
+
+            TimeSeriesVersions versions = dao.getTimeSeriesVersions(cursor, pageSize, tsId, office, begin, end);
+
+            String formatHeader = ctx.header(Header.ACCEPT);
+            ContentType contentType = Formats.parseHeader(formatHeader, TimeSeriesVersions.class);
+            ctx.contentType(contentType.toString());
+
+            String serialized = Formats.format(contentType, versions);
+            ctx.result(serialized);
+            ctx.status(HttpServletResponse.SC_OK);
+            requestResultSize.update(serialized.length());
+        }
+    }
+}

cwms-data-api/src/main/java/cwms/cda/data/dao/TimeSeriesDao.java

@@ -4,6 +4,7 @@
 import cwms.cda.data.dto.Catalog;
 import cwms.cda.data.dto.RecentValue;
 import cwms.cda.data.dto.TimeSeries;
+import cwms.cda.data.dto.TimeSeriesVersions;
 import cwms.cda.data.dto.filteredtimeseries.FilteredTimeSeries;
 import cwms.cda.formatters.csv.CsvConfiguration;
 
@@ -53,6 +54,9 @@ TimeSeries getTimeseries(String cursor, int pageSize, String names, String offic
     TimeSeries getTimeseries(String cursor, int pageSize, TimeSeriesRequestParameters requestParameters);
     FilteredTimeSeries getTimeseries(String page, int pageSize, TimeSeriesRequestParameters requestParameters, FilteredTimeSeriesParameters filterParams);
 
+    TimeSeriesVersions getTimeSeriesVersions(String cursor, int pageSize, String names, String office,
+                                             ZonedDateTime begin, ZonedDateTime end);
+
     String getTimeseries(String format, String names, String office, String unit, String datum,
                          ZonedDateTime begin, ZonedDateTime end, ZoneId timezone);