T124365#2062088 documents the decision of the ArchCom RFC on API content versioning. Accordingly, clients should add an Accept: header with the current Parsoid HTML version to their requests.
Once T128040: Document and implement the REST API format versioning and negotiation policy is resolved, there will be on-wiki documentation about this.
When this is done, will it be possible to expose T71870: Enable DOM editing of transclusion parameters only to a few clients through different Accept: headers?
@Jdforrester-WMF: Accept headers are used for response versioning / negotiation per entry point, but they aren't meant to be used for the selection of fundamentally different resources. Arguably wikitext and HTML versions of data-mw are falling somewhere in between, but I think there are several advantages in exposing those as separate resources, including documentation and the ability to directly link to the latest format of each.
All but google have updated their clients to send the Accept header. Google is waiting for the Accept header to actually be used, so we shouldn't block on them.
Resolving for that reason.
@GWicke , we are using Parsoid API on our prod now, and it's not clear to me what it means by closing this bug, are we seeing any breakage?
@Bianjiang: No, you won't see any breakage right now. However, we are planning breaking changes to the format in the medium term, and encourage you strongly to start sending the accept header now to avoid being surprised by a new default format later.
it seems from T128239, we are waiting for a document to know the expected way to make the change, any update around the document?
As mentioned on the task, https://www.mediawiki.org/wiki/API_versioning#Content_format_stability_and_-negotiation sets out the policy.
We don't implement format conversions for current minor changes, but *will* provide a conversion for the upcoming major change. By providing a version now, you get control over when you upgrade to the latest format after it has been released.