From ec05b4dec9999821db9713fcc642c77c5950e269 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Mon, 13 Jul 2026 11:38:49 -0700 Subject: [PATCH 1/6] Added initial ADR for catalog endpoints. Work in progress. --- docs/source/decisions/0013-catalogs.rst | 63 +++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/source/decisions/0013-catalogs.rst diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst new file mode 100644 index 000000000..f0ecbbeab --- /dev/null +++ b/docs/source/decisions/0013-catalogs.rst @@ -0,0 +1,63 @@ +##### +Catalog endpoint in CDA +##### + +Summary +======= + +This ADR defines a standardized design for CDA catalog endpoints and distinguishes them from getAll endpoints. +GetAll endpoints shall return data that can be passed to the POST endpoint as input (roundtripable). +Catalog endpoints shall only be concerned with retrieval of data without consideration of storing +the data in the same shape it is retrieved in. Data types currently supported by the catalog endpoints are +timeseries and locations. + +Opinions +======== + +Opinion 1 +--------- + +@zack-rma + +Summary +~~~~~~~ +Each data type shall have at most one catalog endpoint. The endpoint shall provide as much data as users might want. + +Key Points +~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 20 25 55 + + * - Topic + - Decision + - Justification + * - Base Path + - Catalog endpoints shall be grouped into the `/catalog/` path group. + - Consistent data access across data types. + +Existing catalog endpoints +========================== + +.. list-table:: + :header-rows: 1 + :widths: 20 25 20 35 + + * - Endpoint path + - Controller + - Notes + * - /catalog/{dataset} + - CatalogController + - Supports TimeSeries and Location data types + +Decision Status +=============== + +(Status: tbd) + +References +========== + + + From 24bcfa2981144c9789966449a6e590915faab710 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 14 Jul 2026 10:50:45 -0700 Subject: [PATCH 2/6] ADR updates --- docs/source/decisions/0013-catalogs.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst index f0ecbbeab..34cc13a56 100644 --- a/docs/source/decisions/0013-catalogs.rst +++ b/docs/source/decisions/0013-catalogs.rst @@ -6,10 +6,10 @@ Summary ======= This ADR defines a standardized design for CDA catalog endpoints and distinguishes them from getAll endpoints. -GetAll endpoints shall return data that can be passed to the POST endpoint as input (roundtripable). +GetAll endpoints shall return data that can be passed to the associated Post endpoint as input (roundtrip). Catalog endpoints shall only be concerned with retrieval of data without consideration of storing the data in the same shape it is retrieved in. Data types currently supported by the catalog endpoints are -timeseries and locations. +time series and locations. Opinions ======== @@ -36,6 +36,10 @@ Key Points * - Base Path - Catalog endpoints shall be grouped into the `/catalog/` path group. - Consistent data access across data types. + * - Paging + - Catalog endpoints shall support paging. + - Efficient retrieval for larger data sets. + Existing catalog endpoints ========================== From e18aeff3b8fdddab0dcbc2f4b699886d8a3fe4ea Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 14 Jul 2026 15:40:24 -0700 Subject: [PATCH 3/6] ADR updates from feedback --- docs/source/decisions/0013-catalogs.rst | 27 ++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst index 34cc13a56..981a8c172 100644 --- a/docs/source/decisions/0013-catalogs.rst +++ b/docs/source/decisions/0013-catalogs.rst @@ -6,10 +6,7 @@ Summary ======= This ADR defines a standardized design for CDA catalog endpoints and distinguishes them from getAll endpoints. -GetAll endpoints shall return data that can be passed to the associated Post endpoint as input (roundtrip). -Catalog endpoints shall only be concerned with retrieval of data without consideration of storing -the data in the same shape it is retrieved in. Data types currently supported by the catalog endpoints are -time series and locations. +Data types currently supported by the catalog endpoints are time series and locations. Opinions ======== @@ -21,7 +18,14 @@ Opinion 1 Summary ~~~~~~~ -Each data type shall have at most one catalog endpoint. The endpoint shall provide as much data as users might want. + +This ADR establishes a standardized design for CDA catalog endpoints that enables efficient data discovery and +retrieval. Catalog endpoints are grouped under a `/catalog/` path and support paging to handle large datasets. +The design explicitly distinguishes catalog endpoints from GetAll endpoints: GetAll endpoints return data suitable +for round-trip storage operations (POST-compatible), while catalog endpoints optimize for retrieval and +discoverability without storage compatibility constraints. To prevent confusion and reduce maintenance burden, +each data type is limited to a single canonical catalog endpoint that provides comprehensive data access. +Currently implemented for TimeSeries and Location data types through the `/catalog/{dataset}` endpoint. Key Points ~~~~~~~~~~ @@ -39,7 +43,16 @@ Key Points * - Paging - Catalog endpoints shall support paging. - Efficient retrieval for larger data sets. - + * - GetAll vs Catalog + - GetAll endpoints shall return data that can be passed to the associated Post endpoint as input (roundtrip). + Catalog endpoints shall only be concerned with retrieval of data without consideration of storing + the data in the same shape it is retrieved in. + - Clearly separated purpose for endpoints. Allows for additional retrieval features without requiring + maintenance to the associated POST endpoint. Permits optimization for readability and discoverability rather than + storage compatibility. + * - Catalog endpoint count + - Each data type shall have at most one catalog endpoint. The endpoint shall provide as much data as users might want. + - Prevents inconsistency and confusion about the proper endpoint to use for desired data. Reduces maintenance burden. Existing catalog endpoints ========================== @@ -53,7 +66,7 @@ Existing catalog endpoints - Notes * - /catalog/{dataset} - CatalogController - - Supports TimeSeries and Location data types + - Currently supports TimeSeries and Location data types Decision Status =============== From 63041e8ef23a913a9c050eaa121785d8f3b2825c Mon Sep 17 00:00:00 2001 From: zack-rma Date: Fri, 17 Jul 2026 13:05:42 -0700 Subject: [PATCH 4/6] Added note on QUERY HTTP method support --- docs/source/decisions/0013-catalogs.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst index 981a8c172..65e194129 100644 --- a/docs/source/decisions/0013-catalogs.rst +++ b/docs/source/decisions/0013-catalogs.rst @@ -53,6 +53,14 @@ Key Points * - Catalog endpoint count - Each data type shall have at most one catalog endpoint. The endpoint shall provide as much data as users might want. - Prevents inconsistency and confusion about the proper endpoint to use for desired data. Reduces maintenance burden. + * - Catalog endpoint HTTP method type + - Catalog endpoints currently support `GET all` requests. Support for `QUERY` requests shall be implemented for + improved functionality. + - Introduced in `RFC 10008`, the `QUERY` HTTP method allows for significantly more complex queries without + running into URL length restrictions or requiring `POST` usage. Unlike `POST`, the `QUERY` method is + idempotent and cacheable, resulting in consistent behavior when a request is received once and when it + is received many times. Like `POST`, `QUERY` permits request data to be included in the body, reducing the + need for a lengthy assortment of query parameters. Existing catalog endpoints ========================== @@ -66,7 +74,7 @@ Existing catalog endpoints - Notes * - /catalog/{dataset} - CatalogController - - Currently supports TimeSeries and Location data types + - Currently supports TimeSeries and Location data types. Uses `GET all` HTTP method. Decision Status =============== @@ -76,5 +84,5 @@ Decision Status References ========== - +- RFC 10008: [https://www.rfc-editor.org/info/rfc10008](https://www.rfc-editor.org/info/rfc10008) From 08c1fb3ebf6965f759759dae671516155851825b Mon Sep 17 00:00:00 2001 From: zack-rma Date: Fri, 17 Jul 2026 16:24:54 -0700 Subject: [PATCH 5/6] Reworded for clarity. Fixed links. --- docs/source/decisions/0013-catalogs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst index 65e194129..34a849aed 100644 --- a/docs/source/decisions/0013-catalogs.rst +++ b/docs/source/decisions/0013-catalogs.rst @@ -59,7 +59,7 @@ Key Points - Introduced in `RFC 10008`, the `QUERY` HTTP method allows for significantly more complex queries without running into URL length restrictions or requiring `POST` usage. Unlike `POST`, the `QUERY` method is idempotent and cacheable, resulting in consistent behavior when a request is received once and when it - is received many times. Like `POST`, `QUERY` permits request data to be included in the body, reducing the + is received many times. Like `POST`, `QUERY` supports data provided in the request body, reducing the need for a lengthy assortment of query parameters. Existing catalog endpoints @@ -67,7 +67,7 @@ Existing catalog endpoints .. list-table:: :header-rows: 1 - :widths: 20 25 20 35 + :widths: 20 25 35 * - Endpoint path - Controller @@ -84,5 +84,5 @@ Decision Status References ========== -- RFC 10008: [https://www.rfc-editor.org/info/rfc10008](https://www.rfc-editor.org/info/rfc10008) +- RFC 10008: https://www.rfc-editor.org/info/rfc10008 From 768199d9b566771b21109dff85959d48039ae961 Mon Sep 17 00:00:00 2001 From: zack-rma Date: Tue, 28 Jul 2026 10:31:55 -0700 Subject: [PATCH 6/6] Added details about QUERY implementation. Added example for distinction between catalog and getall endpoints --- docs/source/decisions/0013-catalogs.rst | 127 +++++++++++++++++++++++- 1 file changed, 126 insertions(+), 1 deletion(-) diff --git a/docs/source/decisions/0013-catalogs.rst b/docs/source/decisions/0013-catalogs.rst index 34a849aed..624023415 100644 --- a/docs/source/decisions/0013-catalogs.rst +++ b/docs/source/decisions/0013-catalogs.rst @@ -62,6 +62,127 @@ Key Points is received many times. Like `POST`, `QUERY` supports data provided in the request body, reducing the need for a lengthy assortment of query parameters. +Differences in Catalog and GetAll data shapes +============================================= + +An important distinction between the two endpoint types is the shape of the data retrieved. +Below is an example for the Location endpoints: + +GetAll: + +.. code:: json + + [ + { + "office-id": "string", + "name": "string", + "latitude": 0, + "longitude": 0, + "active": true, + "public-name": "string", + "long-name": "string", + "description": "string", + "timezone-name": "string", + "location-type": "string", + "location-kind": "string", + "nation": "US", + "state-initial": "string", + "county-name": "string", + "nearest-city": "string", + "horizontal-datum": "string", + "published-longitude": 0, + "published-latitude": 0, + "vertical-datum": "string", + "elevation": 0, + "map-label": "string", + "bounding-office-id": "string", + "elevation-units": "string", + "aliases": [ + { + "name": "string", + "value": "string" + } + ] + } + ] + +Catalog: + +.. code:: json + + { + "entries": [ + { + "office": "string", + "name": "string", + "nearest-city": "string", + "public-name": "string", + "long-name": "string", + "description": "string", + "kind": "string", + "type": "string", + "time-zone": "string", + "latitude": 0, + "longitude": 0, + "published-latitude": 0, + "published-longitude": 0, + "horizontal-datum": "string", + "elevation": 0, + "unit": "string", + "vertical-datum": "string", + "nation": "string", + "state": "string", + "county": "string", + "bounding-office": "string", + "map-label": "string", + "active": true, + "aliases": [ + { + "name": "string", + "value": "string" + } + ] + }, + { + "office": "string", + "name": "string", + "units": "string", + "interval": "string", + "interval-offset": 0, + "time-zone": "string", + "extents": [ + { + "earliest-time": "2026-07-28T16:49:26.200Z", + "latest-time": "2026-07-28T16:49:26.200Z", + "version-time": "2026-07-28T16:49:26.200Z", + "last-update": "2026-07-28T16:49:26.200Z" + } + ], + "aliases": [ + { + "name": "string", + "value": "string" + } + ], + "versioned": true + } + ], + "next-page": "string", + "page": "string", + "page-size": 0, + "total": 0 + } + +Library Support for HTTP QUERY method +===================================== + +Support for the QUERY method has been added to Jakarta EE 12 and Apache Tomcat 12. Currently, CDA is using Java EE 8 +and will require a version bump to make this feature available. This involves a namespace change in the associated +packages from javax.* to jakarta.*. This transition should be conducted in parallel with a bump in Javalin, which +also requires the newer namespace in its more recent versions. Note that this version bump may also require Java 17, +which is not compatible with Solaris-based systems. See references section below for relevant issue links +and commits into the Tomcat and Jakarta libraries. + Existing catalog endpoints ========================== @@ -85,4 +206,8 @@ References ========== - RFC 10008: https://www.rfc-editor.org/info/rfc10008 - +- QUERY method support: + - CDA Issue 1850: https://github.com/USACE/cwms-data-api/issues/1850 + - Jakarta EE: https://github.com/jakartaee/servlet/issues/1068 + - Apache Tomcat: https://github.com/apache/tomcat/commit/5e01091299e41bc79509b1c8d17486f85df1d872 +- Javalin update issue (linked to Jakarta version): https://github.com/USACE/cwms-data-api/issues/1004