[Flix6x]

Description

Settles the API names that 1.1.0 would otherwise ship in a spelling we'd have to support, and widens the naming test that should have caught one of them.

• GET /sensors/<id>/status takes asset, not asset_id. The query parameter came in with Fix what the asset status page reports about its sensors #2474, after v1.0.1, so no release accepted asset_id and it is renamed without an alias. The sensor status page, its only caller, is updated. The sensor listing already takes asset (with asset_id as a legacy alias), so the two now agree.
• Both DELETE sensor endpoints take start and end. They took start and until, where POST .../annotations and every other time window in the API take start and end.
  • DELETE /sensors/<id>/data shipped with until, so it keeps accepting until as a deprecated alias (via SupportsLegacyFieldAliases).
  • DELETE /sensors/<id>/annotations is new in 1.1.0, so it takes no alias and refuses until with a 422.
• The naming test now also checks the published OpenAPI specs. test_field_naming.py (Hold new field names to kebab-case, and list the ones that predate it #2547) walks the Marshmallow schemas defined in FlexMeasures modules. That missed asset_id, because a parameter declared inline, as in @use_kwargs({"asset": AssetIdField(data_key="asset_id")}), gets a schema that Marshmallow generates in its own module. Response fields built as plain dicts have no schema to walk either. Two new tests check the query/header/cookie parameters and the body properties named in the specs against the same list of names that predate kebab-case. The 14 names only the specs reveal all shipped in v1.0.1, so they join that list. The stale-entry test now counts names found in the specs too.
• The API change log spells the 1.1.0 changes the way the API does. It said next_run and n_jobs, where the API sends next-run and n-jobs. The main changelog and the automation trigger's description had the same slips. It now also describes asset and end above, and the deprecation of until.
• Added changelog item in documentation/changelog.rst

The regenerated OpenAPI specs also pick up the PATCH asset description from #2825, which main's specs had not caught up with.

Look & Feel

DELETE /api/v3_0/sensors/1/data         {"start": "...", "end": "..."}    → 204
DELETE /api/v3_0/sensors/1/data         {"start": "...", "until": "..."}  → 204 (deprecated)
DELETE /api/v3_0/sensors/1/annotations  {"until": "..."}                  → 422
GET    /api/v3_0/sensors/1/status?asset=2

A new snake_case parameter in the specs now fails like this:

AssertionError: these parameters are named with an underscore in the OpenAPI specs:
  asset_id: GET /api/v3_0/sensors/{id}/status

How to test

• pytest flexmeasures/data/schemas/tests/test_field_naming.py
• pytest flexmeasures/api/v3_0/tests/test_sensors_api.py -k status
• pytest flexmeasures/api/v3_0/tests/test_sensors_delete_data_fresh_db.py flexmeasures/api/v3_0/tests/test_annotations.py

Each new test was checked against the change it covers:

• naming asset_id again fails the status test;
• dropping the until alias fails the data endpoint's until case;
• giving the annotations endpoint that alias fails its refusal test;
• main's spec fails the new parameter check;
• removing a response property from the list fails the new property check.

Further Improvements

• Name the fields of a sensor's status in kebab case, with a deprecation period for the snake case ones #2770 / Name sensor status fields in kebab case, with deprecated aliases #2773 (1.2.0) rename the snake_case fields in the status response itself, such as staleness_since and asset_name. The new property check does not see those: the endpoint documents them only as examples, not as a schema.
• Settle the snake_case to kebab-case field naming migration #2540 still needs a decision on the naming policy as a whole.

Related Items

Follows up on #2547 and #2474.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

🤖 Generated with Claude Code

https://claude.ai/code/session_01DWv6v5ELzmj2eBM1L4GTBz

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #35665007 | 📁 Comparing 5183405 against latest (8a1f508)

  🔍 Preview build  

4 files changed

± changelog.html
± _autosummary/flexmeasures.api.v3_0.sensors.html
± api/change_log.html
± api/v3_0.html