ADR 0014 (proposed): Service declarations and OGC endpoints

[thodson-usgs]

Summary

Proposes ADR 0014, Declare services, endpoints, and dialects as values, and lands its first steps: one Service declaration per adapter. Replaces #444, whose OgcService bundled a name, a URL and a dialect into one OGC-only value. The name and default URL aren't OGC-specific, and Water Data is one service with four APIs.

The ADR (Proposed) defines six abstractions: service, endpoint, protocol, dialect, execution and adapter. Its rules: values are data and protocols are functions; shared code names no service; each dialect field defaults to the standard; dates are read once and written by each protocol; a protocol gets a module only once two endpoints share it. It's revised as each step lands (see its Notes) and accepted at the last step. The glossary adds Service declaration, Endpoint and Protocol, and rewords Adapter and Dialect.

Step 1: service declarations. Each adapter declares Service(name, default_url) once, in the module that owns its URL. Every read site now takes the name from that declaration: the Configuration class's adapter, the adapter= passed to retry, fan-out and pagination, and the base URL via the new configuration.service_url(). Water Data declares one service in waterdata.endpoints, shared by its OGC, Samples, Statistics and STAC APIs. No behavior change.

Tests

• A new fitness function fails if a service's name appears as a code literal anywhere but its declaration and the configuration roster. I checked that it fails on a planted literal in ogc/engine.py.
• The existing read-site test now follows the declarations. I checked that it still fails when an adapter's read site is removed.
• New test: service_url uses the default unless a base_url setting for that adapter overrides it.
• The full offline suite passes (1,326 tests at the current head), and coverage is 99.14%. ruff, mypy, import-linter, xenon and complexipy are clean.

Step 2: endpoints for the OGC getters. The Water Data and NGWMN adapters each build an Endpoint(service, url, dialect) when a call starts. get_ogc_data, _construct_api_requests and _finalize_ogc take that one value instead of separate base_url, dialect and adapter arguments. DEFAULT_DIALECT was unused afterwards, so I removed it. New tests check that the engine reads the URL, dialect and settings from the endpoint, and that a call interrupted inside configure(base_url=...) still resumes against that mirror after the block exits. No behavior change.

Step 3: no endpoints for the other adapters, by decision. The ADR now records why. An Endpoint value exists only where shared protocol code receives one. WQP, NLDI, NWDC, StreamStats, Samples and Statistics have no shared protocol code, so for them an endpoint would carry no dialect and would only repeat a URL lookup that already exists.

Step 4: one date-range value, read when a getter is called. dataretrieval._dates reads a date argument into a DateRange: an instant, a range with open bounds, or a duration. prepare_request_args reads every OGC date parameter this way, and get_ratings reads its time. The request builders only write the value.

Step 5: one interval writer for OGC and STAC, adjusted by DateDialect. dataretrieval._intervals replaces ogc.dates. DateDialect records the open-start spelling and whether a lone duration is accepted (step 7 moved its OGC-only fields to OgcDialect). OgcDialect.dates holds it, and get_ratings reaches STAC through an Endpoint with its own. Behavior change: ngwmn.get_water_level(datetime="P7D") now raises ValueError when called, instead of failing with HTTP 400 (NEWS entry added). get_ratings drops its own duration check for the shared one, so its message changes. New live tests check open_start and durations against Water Data OGC, NGWMN and STAC. All three pass as of 2026-10-11.

Step 6: the OGC code names nothing a dialect declares. OgcDialect has dates and shaping groups; ShapingDialect holds the time, numeric, sort and extra-id columns. extra_id_cols moves there from a get_ogc_data argument. #446's lists_as_cql2 switch replaces cql2_services. The chunk planner no longer lists date parameters, because a DateRange is never split. A new fitness function fails if a string a shipped dialect lists appears as a literal in ogc or _intervals; monitoring_location_id, a deviation the ADR records, is the only allowlisted entry. I checked that it fails on a planted "time".

Steps 4–6 went through simplify and the two-axis review, and the findings are fixed in the last two commits.

Found while writing live tests: whether the Water Data API reads a comma-joined GET value as a list depends on the parameter, not the collection, so a per-collection field recorded the wrong behavior. #446 fixed that on main with the per-API switch OgcDialect.lists_as_cql2; main is merged into this branch, and the switch takes the old field's place in the regrouped OgcDialect.

Step 7: one dialect reads and writes a call's dates. Review findings after the merge:

• DateDialect holds only the interval grammar STAC and OGC share (open_start, durations). date_params, date_only_collections and timed_params are OgcDialect fields, since only OGC reads them.
• prepare_request_args takes the OgcDialect the endpoint carries, and given none reads no date. The Samples and Statistics getters call _get_query_args, which passes none, instead of opting out with a _NO_DATES sentinel.
• get_ogc_data reads any date argument still raw with the endpoint's dialect, and raises when a DateRange arrives under a key that dialect doesn't list. Bug fix: get_reference_table(query={"last_modified": ...}) raised AttributeError on this branch, because a raw query skips argument reading.
• Date arguments are annotated DateArgument (a string, date, datetime or Timestamp, or a list of them with None for an open end), which matches what the 10/09 NEWS entry says they accept. A typed caller passing time=[df.index.min(), None] failed mypy with the old hints; it passes now.
• The merge and these steps went through simplify and code review again. The related live tests and a live Samples and Statistics smoke test pass.

Merge order

#446 has landed and is merged into this branch. Steps 4–6 build on #442 and #443, which are merged into this branch, so their changes show in this diff until they land. Once they merge, those commits drop out of the diff. This PR's NEWS entries need their land date when it merges.

Next step

Accept ADR 0014: reconcile the record with what was built, mark it Accepted, and update the architecture overview.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HBt3Ee7eneKtdKQWq2T3YK

[thodson-usgs]

Closing in favor of step-sized PRs off current main, starting with #448 (step 1: the date read/write split and a shortened ADR 0014).

This branch built all seven steps of the draft ADR at once and now conflicts with main in 10 files, mostly the date code that #442 and #443 just rewrote. The design is kept; the ADR in #448 lists the remaining two steps:
2. OGC date fields on OgcDialect and the dialect-literal test;
3. Service and Endpoint, and the service-name test.

The refactor/service-endpoint branch stays as the reference for porting those steps.