Planned API v4: candidate breaking changes and deprecation tracking

[Flix6x]

Purpose

A running list of API changes we're deferring to a future major API version ("v4"), rather than deprecating field-by-field within v3_0. See the discussion on PR #2224 for the reasoning: field-level deprecation headers proved hard to make meaningful (no committed removal date, non-standard header, awkward client discoverability), whereas a whole-version bump lets us reuse the existing endpoint-level Deprecation/Sunset/Link mechanism (flexmeasures/api/sunset/__init__.py) with a real, host-anchored timeline.

There is no immediate need or plan to actually create v4. This discussion exists so that:

1. Candidate breaking changes have one place to land as they're discovered, instead of getting deprecated ad hoc or forgotten.
2. It doubles as the starting point for an eventual upgrade manual/tutorial for v3_0 → v4 clients — by the time v4 ships, we expect it'll often be enough to point a client's AI agent at our MCP server or at this upgrade guide, rather than hand-holding every field rename.
3. Naming convention going forward: from v4 onward, API versions use a single identifier (v4, v5, ...) instead of the two-part v3_0/v3_1 scheme — versions are meant to be full, deliberate cuts, not something we bump incrementally within a line.

Candidate changes for v4 (living list)

Background job response fields (from PR #2224)

• Remove legacy schedule field from scheduling trigger responses (POST /sensors/<id>/schedules/trigger, POST /assets/<id>/schedules/trigger); canonical field is job.
• Remove legacy forecast field from POST /sensors/<id>/forecasts/trigger; canonical field is job.
• Remove legacy snake_case job-status fields (func_name, enqueued_at, started_at, ended_at, exc_info) from GET /api/v3_0/jobs/<uuid>; canonical fields are kebab-case (func-name, enqueued-at, started-at, ended-at, exc-info).

(More candidates to be added as they come up — this list will grow before v4 is ever scheduled.)

Open questions

• Do we keep two "get job status" endpoints long-term (GET /jobs/<uuid> for generic status, plus the sensor-specific GET /sensors/<id>/schedules/<uuid> / .../forecasts/<uuid> for results), or consolidate? (raised in PR use the 202 status consistently in triggering endpoints  #2224 review, out of scope there)
• Host-configurable deprecation/sunset timing (FLEXMEASURES_DEPRECATION_AND_SUNSET-style config), so a host's actual upgrade cadence — not the FlexMeasures release date — drives when Deprecation/Sunset headers go out. Currently only whole API versions can be deprecated this way; see flexmeasures/api/sunset/__init__.py.

[Flix6x]

Verified candidate list (checked against current main, 2026-07-22)

Naming-policy reference from #2127:

1. Single word, unless ambiguous — first choice
2. Hyphenated — only when disambiguation is needed
3. Underscored — accidental legacy debt (copied from DB column names), not a design tier

Legacy key	Surface	Candidate	Verified live?
flex_model (asset body, generic_assets.py:441) vs flex-model (trigger body)	body	same concept, two spellings — align on flex-model	✅
flex_context (asset body, generic_assets.py:440) vs flex-context (trigger body)	body	align on flex-context	✅
account_id (query filter, assets/sensors/users)	query	account	✅ assets.py:57-58, sensors.py:224
asset_id (query filter, sensors)	query	asset	✅ sensors.py:225
generic_asset_id (sensor body/response)	body/response	asset (per the #2127 example)	✅ widely used, e.g. SensorSchema
per_page (all paginated endpoints)	query	per-page	✅ generic_schemas.py:8
sort_by (all paginated endpoints)	query	sort-by	✅ generic_schemas.py:17
sort_dir (all paginated endpoints)	query	sort-dir	✅ generic_schemas.py:23
consultancy_account_id (account body/response)	body/response	consultancy (per the #2127 example)	✅ account.py:49,130,187
parent_asset_id (asset body)	body	parent	✅ generic_assets.py:431
primary_color, secondary_color, logo_url (account body/response)	body/response	primary-color, secondary-color, logo-url	✅ account.py:44-46,184-186

Dropped from the original (AI-generated) audit after verification:

• force_new_job_creation "inconsistency" — stale, already fixed on main (data_key="force-new-job-creation" is live).
• prior → belief_time/beliefs_before internal Python-variable mismatch — not client-visible, not an API surface concern.
• sort_keys vs sort doc bug — unrelated to versioning (server already only accepts sort, docs were just wrong) — fixed directly in Fix OpenAPI docs: GET /sensors/<id>/stats accepts sort, not sort_keys #2351, no need to wait for v4.

Request-side migration doesn't need to wait for v4

Response fields need duplication to stay backward-compatible (job+schedule, func-name+func_name, as done in #2224/#2350) since a response can't "accept either" key. But request fields can accept both the legacy and canonical spelling immediately, via a @pre_load hook — this pattern already exists (GetSensorDataFilterSchemaMixin.support_legacy_field_name in sensor_data.py:188-191, currently applied to exactly one schema) and can be generalized into a shared mixin using the already-present-but-unused snake_to_kebab/kebab_to_snake helpers in data/schemas/utils.py.

Concretely: force-new-job-creation doesn't have this shim, which is why flexmeasures-client had to build client-side server-version sniffing instead of the server just accepting both spellings (see flexmeasures-client#218's description, which explicitly documents a 422 rejection of the legacy key). That's the kind of avoidable client-side workaround this generalization would eliminate.

Opening a follow-up PR now that generalizes the pre_load alias mixin and applies it to the query-filter/pagination keys above (per_page/sort_by/sort_dir, account_id, asset_id, force_new_job_creation) — pure backward-compatible additions, no v4 needed for these. The body/response fields with dump-side symmetry needs (generic_asset_id, flex_model/flex_context, consultancy_account_id, parent_asset_id, the account color/logo fields) need the dual-field-output treatment like #2224/#2350 did for job fields, which is a larger, separate effort — still tracked here for v4, not yet scheduled.