use the 202 status consistently in triggering endpoints

[nhoening]

Description

Use 202 in triggering endoints (forecasting scheduling) and provide follow-up URLs in the response.

Closes #2171

• changes three trigger endpoint to return 202 when the job is accepted (instead of 200): sensor schedule trigger, asset schedule trigger, and sensor forecast trigger.
• updates tutorial docs, too: toy-example-expanded.rst and toy-example-from-scratch.rst.
• introduces job_id as the canonical response field while keeping legacy schedule / forecast fields for compatibility.
• adds _deprecated_fields metadata, to deprecate fields in endpoints, and for schedule / forecast fields, employ it with use: "job_id" and deprecated_since: "1.0.0".
• generalizes request_accepted_for_processing(...) so accepted job responses can include legacy keys and result URLs.

Look & Feel

Mainly Sphinx and Swaggerdocs.

How to test

The only new test is test_get_schedule_unfinished_job_returns_202_when_sunset_active.

A bunch of tests simply check for 202 now instead of 200.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33590402 | 📁 Comparing 946f996 against latest (4a5892f)

  🔍 Preview build  

28 files changed · + 1 added · ± 27 modified

+ Added

• host/multi-tenancy.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• _autosummary/flexmeasures.api.common.responses.html
• _autosummary/flexmeasures.api.v3_0.accounts.html
• _autosummary/flexmeasures.api.v3_0.assets.html
• _autosummary/flexmeasures.api.v3_0.jobs.html
• and 17 more...

[Flix6x]

Rationale: API policy specifies no id in API keys.

Suggested change

	"job_id": "364bfd06-c1fa-430b-8d25-8f5a547651fb",
	"job": "364bfd06-c1fa-430b-8d25-8f5a547651fb",

[Flix6x]

Rationale:

• API policy specifies kebab-case keys in API
• (to discuss) Not just for progress monitoring; (some) results live there, too. Do we want to keep two endpoints? Right now we have one for the schedule, and the other for job progress and constraints analysis, and I am at least planning to also let it contain the core result (schedule, forecast, report).

Suggested change

	"job_monitor_url": "/api/v3_0/jobs/364bfd06-c1fa-430b-8d25-8f5a547651fb",
	"job-url": "/api/v3_0/jobs/364bfd06-c1fa-430b-8d25-8f5a547651fb",

[nhoening]

Do we want to keep two endpoints?

Are you suggesting to deprecate GET /api/v3_0/sensors/{id}/schedules/{uuid} and GET /api/v3_0/sensors/{id}/forecasts/{uuid}

I believe that could make things easier. Less endpoints to learn for users, for us to maintain.
Once, we discussed making a REST-like resource for scheduling jobs, forecasting jobs (and now possibly also reporting jobs). I don't think we want to really go there anymore. Triggering does live on asset and sensor resources, though. I am curious where reporting triggers will live.

Anyway, with that discussion we're moving out of the scope of this PR here.

For here, I am fine to (already) work with results-url, as you suggest below, next to job-url. One of them could be retired later, but I don't know which right now.

[Flix6x]

The cross-reference is just throwing up another curtain. You have to find the section below, then read it to notice it has almost nothing to add, then follow up on the reference there to actually find more info.

Better would be to directly cross-reference some material that is actionable to clients, rather than an issue or PR. In addition, that material might reference the new docs on deprecation notices in responses.