Page MenuHomePhabricator

All known clients of Parsoid HTML (either directly hitting Parsoid or via RESTBase) should provide Accept: headers in their requests
Closed, ResolvedPublic

Description

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.

Related Objects

Event Timeline

ssastry created this task.Feb 26 2016, 11:15 PM
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald Transcript
ssastry renamed this task from Add Accept: header to your HTML requests to RESTBase/Parsoid as per T124365 to All known clients of Parsoid HTML (either directly or via RESTBase) should provide Accept: headers in their requests.Feb 26 2016, 11:27 PM
ssastry triaged this task as High priority.
ssastry updated the task description. (Show Details)
ssastry removed subscribers: Renxiaoyi, Bianjiang, bearND, Jackmcbarn.
ssastry renamed this task from All known clients of Parsoid HTML (either directly or via RESTBase) should provide Accept: headers in their requests to All known clients of Parsoid HTML (either directly hitting Parsoid or via RESTBase) should provide Accept: headers in their requests.Feb 26 2016, 11:39 PM

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?

GWicke added a subscriber: GWicke.EditedMar 1 2016, 1:19 AM

@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.

ssastry raised the priority of this task from High to Needs Triage.May 27 2016, 11:19 PM
ssastry triaged this task as High priority.
ssastry moved this task from Backlog to In Progress on the Parsoid board.
GWicke closed this task as Resolved.Oct 12 2016, 5:41 PM
GWicke claimed this task.

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?

GWicke added a comment.EditedOct 13 2016, 12:21 AM

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.