Drop field-level deprecation headers from #2224; track field removal in API v4 discussion#2350
Open
Flix6x wants to merge 2 commits into
Conversation
…dditive The `job`/`schedule`/`forecast` and kebab-case/`snake_case` job-status field pairs stay additive within v3_0, with no per-field `Deprecation`/ `Link`/`FlexMeasures-Deprecated-Response-Fields` signalling. That custom header wasn't standard, forced clients to special-case it before they could even interpret the standard `Deprecation` header, and was carrying a deprecation date with no committed removal plan behind it. Any eventual removal of the legacy fields is deferred to a future major API version, following the existing whole-endpoint deprecation/sunset mechanism, rather than field-by-field within v3_0. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Documentation build overview
33 files changed ·
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Follow-up to #2224 (base branch:
feat/api/use-202-status-consistenly-in-triggering-and-fetching-endpoints), addressing feedback discussed there on the deprecation/discoverability design for the new response fields.Why
#2224 introduced a custom
FlexMeasures-Deprecated-Response-Fieldsresponse header (plus reusedDeprecation/Linkheaders) to signal that the legacyschedule/forecast/snake_case job-status fields are deprecated in favor ofjob/kebab-case fields, all within API versionv3_0.On review we concluded this design has three problems:
JOB_RESPONSE_FIELDS_DEPRECATION_DATE), not tied to when any host actually deploys the change, and not backed by a decided target version. ADeprecationheader is supposed to be an actionable signal ("plan your migration by X"); shipping it without a committed timeline undermines that for this and future deprecations.Sunset) nor the IETFDeprecationheader draft define field-level deprecation —FlexMeasures-Deprecated-Response-Fieldsis our own invention, and worse, it inverts the usual relationship: a client has to check for this custom header just to know how to interpret the standardDeprecationheader (endpoint-wide vs. field-scoped).flexmeasures/api/sunset/__init__.pyalready deprecates/sunsets whole API versions with paireddeprecation_date/sunset_date, decided together, once a replacement exists. Signalling field-level deprecation before a replacement version even exists inverts that sequencing.What changed here
deprecated_response_fields_headers()and theFlexMeasures-Deprecated-Response-Fieldsheader entirely.job(and, for job status, the kebab-case fields) are added purely additively next to the existingschedule/forecast/snake_case fields — no header signalling, no formal HTTP deprecation.flexmeasures/api/v3_0/deprecations.pymodule and its hardcoded deprecation date.documentation/api/introduction.rstanddocumentation/api/change_log.rstto describe the additive fields plainly, with a docs note recommending new clients use the canonical fields, and a link to the tracking discussion below.202/422/200status-code work from use the 202 status consistently in triggering endpoints #2224 unchanged — that's a same-version bug fix (status code stays within the 2xx success range), not a breaking API change.Where the actual removal will happen
Opened #2349 ("Planned API v4: candidate breaking changes and deprecation tracking") as a living list of changes deferred to a future major API version. Removing
schedule/forecast/snake_case job-status fields is tracked there as the first candidate. There is no immediate plan to create v4 — the discussion exists so candidate breaking changes have one place to land, and so it can double as a starting point for an eventual upgrade guide.How to test
No behavioral change to status codes or to the new
job/kebab-case fields introduced in #2224 — only the deprecation-signalling headers and hardcoded date are removed, and legacy fields keep working exactly as before. Existing tests from #2224 were updated to drop assertions on the removed headers; no new test scenarios were needed since nothing user-facing about the successful-response shape changed.