On the Parsoid end, we have to figure out if we should add a lint=true param to https://www.mediawiki.org/wiki/Parsoid/API#Wikitext_-.3E_HTML_2 or if we should add a separate linting endpoint.

@Arlolra says: "at first glance, a qs param or flag in the payload might be ok, but only supported in pagebundle".

Sounds reasonable, although if we make "saving the page and waiting for the list of errors to get updated" really fast, that would also work. Not sure which is easier.

@cscott : the idea of this request was to be able to check if there are remaining errors before saving the page, so that you can fix them without saving multiple versions of the page...

In T163091#3194786, @ssastry wrote:

@Arlolra says: "at first glance, a qs param or flag in the payload might be ok, but only supported in pagebundle".

If the lint issues are sent in the response in addition to the HTML output then the pagebundle and wt2html endpoints are the right thing to do.

However, if only lint issues are required, then a separate lint endpoint is better since that will not return html, data-parsoid, data-mw, etc. and /lint/ is a better description of what is expected.

Would this need to be project dependent?

In T163091#3219482, @mobrovac wrote:

Would this need to be project dependent?

If I understand you correctly yes? Because lint errors depend upon local context like localized image options, etc.

In T163091#3219482, @mobrovac wrote:

Would this need to be project dependent?

IRC transcript regarding exposing the endpoint via the REST API in restbase.

<subbu> mobrovac, i didn't actually understand your qn. about "would this need to be project dependent?"
<mobrovac> subbu: oh sorry, the q is whether the api would need to be exposed per-project or would it be possible to put it under the global domain
<subbu> isn't it better to do it per-project like all other endpoints since it is basically a parse + extra analysis.
<mobrovac> subbu: the reason i'm asking is because this smells like a feature that would be useful only to us, not the public, so having it just on the global domain would give it less visibility
<subbu> I see what you are saying ..

Oh, hm, wait, so this would be consulted on every edit? What would be the exact flow for this API?

In T163091#3226324, @mobrovac wrote:

Oh, hm, wait, so this would be consulted on every edit? What would be the exact flow for this API?

Probably not. The workflow is probably going to be that a tool/gadget/user retrieves a list of lint errors for a page from the MW API. It then fixes up the text to resolve those lint errors. Then it posts that text to this new API endpoint that tells the client if there are any lint errors left. Repeat until lint errors are gone (or user is satisfied with what is left), and then it'll save the page using the normal MW API.

In T163091#3226343, @Legoktm wrote:

In T163091#3226324, @mobrovac wrote:

Oh, hm, wait, so this would be consulted on every edit? What would be the exact flow for this API?

Probably not. The workflow is probably going to be that a tool/gadget/user retrieves a list of lint errors for a page from the MW API. It then fixes up the text to resolve those lint errors. Then it posts that text to this new API endpoint that tells the client if there are any lint errors left. Repeat until lint errors are gone (or user is satisfied with what is left), and then it'll save the page using the normal MW API.

Isn't linting on preview also a use case?

In T163091#3226348, @ssastry wrote:

Isn't linting on preview also a use case?

Yes but we'll probably only do this for users that care and opt-in somehow and not everyone since most users probably won't understand or know how to fix the errors.

In T163091#3226351, @Legoktm wrote:

In T163091#3226348, @ssastry wrote:

Isn't linting on preview also a use case?

Yes but we'll probably only do this for users that care and opt-in somehow and not everyone since most users probably won't understand or know how to fix the errors.

Makes sense. I was checking that we had this preview use case in mind, even if it is only going to be a fraction of edits that will have that workflow.

I see, thank you for the context @Legoktm and @ssastry . So, it would lint the wikitext content. Is the domain/title relevant then? I would suppose the domain is (for templates and such), but if the goal is to have linter-approved wikitext, then I must say I'm not sure how knowing the title might help. Please educate me :)

Title is necessary for parsing page-specific variables e.g. {{PAGENAME}} and everything that builds on top of that.

In that case, I think we can expose it publicly under /page/, e.g. POST https://en.wikipedia.org/api/rest_v1/page/lint/Foobar. Similarly, Parsoid could expose a similar path and requests would then just be proxied from RB to it.

I'm not 100% sure on the /lint/ portion of the path. /lint-wikitext/ would probably be more accurate, but it's kind of long. Thoughts?

My first thought was that this fits with the other transform end points, which are all stateless, and also optionally take a title parameter. Perhaps /transform/wikitext/to/lints{/title} ?

Change 352715 had a related patch set uploaded (by Arlolra; owner: Arlolra):
[mediawiki/services/parsoid@master] WIP: Add an API endpoint to get lint errors for arbitrary wikitext

https://gerrit.wikimedia.org/r/352715

In T163091#3243285, @GWicke wrote:

My first thought was that this fits with the other transform end points, which are all stateless, and also optionally take a title parameter. Perhaps /transform/wikitext/to/lints{/title} ?

That was my first thought as well, but it sounds ... weird (can you transform wikitext to lints?) and it doesn't really transform anything, rather, it evaluates it.

In T163091#3246143, @mobrovac wrote:

In T163091#3243285, @GWicke wrote:

My first thought was that this fits with the other transform end points, which are all stateless, and also optionally take a title parameter. Perhaps /transform/wikitext/to/lints{/title} ?

That was my first thought as well, but it sounds ... weird (can you transform wikitext to lints?)

Yeah, I had a similar worry. I think it is mainly weird when looking at it with the "transform content" pattern currently dominating the transform hierarchy in mind. However, we partly chose "transform" because it is a very general term that can describe pretty much any kind of input to output transformation, as in f(x) = y. Linting fits that more general meaning, and expanding the transform hierarchy that way would let us limit the number of top level hierarchies by using transform as a fairly general catch-all.

The page hierarchy on the other hand is currently focused on content and data associated with specific, typically existing pages. It would certainly be a good place for a GET /page/lint/{title}{/revision} end point backed by storage. If we plan to add such an entry point, then a symmetric POST end point could make sense as well, although this is somewhat different with how we have done this for wikitext.

Please note that the request is for arbitrary wikitext : the endpoint must allow to provide the wikitext for the given page, independently of any existing revision (or even if the page exists at all or not). When I read your comments, I'm not sure this is still taken into account.

Change 352715 had a related patch set uploaded (by Arlolra; owner: Arlolra):
[mediawiki/services/parsoid@master] T163091: Add an API endpoint to get lint errors for arbitrary wikitext

https://gerrit.wikimedia.org/r/352715

In T163091#3246612, @NicoV wrote:

Please note that the request is for arbitrary wikitext : the endpoint must allow to provide the wikitext for the given page, independently of any existing revision (or even if the page exists at all or not). When I read your comments, I'm not sure this is still taken into account.

POST requests allow for arbitrary wikitext to be posted. title and revision are optional. app.post('/:domain/v3/transform/:from/to/:format/:title?/:revision?) is the definition inside Parsoid for example. If you provide the page title, the wikitext is evaluated in the context of the page title. (defaults to Main Page if not provided).

RESTBase also has a similar interpretation. See https://en.wikipedia.org/api/rest_v1/#!/Transforms/post_transform_wikitext_to_html_title_revision

Makes sense. Let's go with /transform/wikitext/to/lint{/title}, then ?

In T163091#3250379, @mobrovac wrote:

Makes sense. Let's go with /transform/wikitext/to/lint{/title}, then ?

wfm.

Change 352715 had a related patch set uploaded (by Arlolra; owner: Arlolra):
[mediawiki/services/parsoid@master] Add an API endpoint to get lint errors for wikitext

https://gerrit.wikimedia.org/r/352715

The RESTBase side of things is covered in PR 816.

Change 352715 merged by jenkins-bot:
[mediawiki/services/parsoid@master] Add an API endpoint to get lint errors for wikitext

https://gerrit.wikimedia.org/r/352715

Mentioned in SAL (#wikimedia-operations) [2017-05-15T20:20:02Z] <subbu> Updated Parsoid to a182c227 (T141226, T164792, T37247, T153107, T163091, T164006, T161151, T162920, T163549)

Mentioned in SAL (#wikimedia-operations) [2017-05-15T21:13:08Z] <mobrovac@tin> Started deploy [restbase/deploy@c52add0]: Expose the new /transform/wikitext/to/lint end point to the public - T163091

Mentioned in SAL (#wikimedia-operations) [2017-05-15T21:19:40Z] <mobrovac@tin> Finished deploy [restbase/deploy@c52add0]: Expose the new /transform/wikitext/to/lint end point to the public - T163091 (duration: 06m 32s)

Mentioned in SAL (#wikimedia-operations) [2017-05-15T22:16:50Z] <mobrovac@tin> Started deploy [restbase/deploy@d98af6f]: Wt2lint bug fix - T163091

Mentioned in SAL (#wikimedia-operations) [2017-05-15T22:23:34Z] <mobrovac@tin> Finished deploy [restbase/deploy@d98af6f]: Wt2lint bug fix - T163091 (duration: 06m 44s)