Talk:Parsoid/API

The page mentions

GET /:domain/v3/page/:format/:title/:revision?

api/rest_v1 recommends

post /transform/wikitext/to/lint{/title}{/revision}

Imagine pages as follows:

1. 2017
2. User talk:Itu/Archiv/2016
   • User talk:Itu/Archiv (presumable archive overview)

How is it distinguished or interpreted?

1. Is 2017 a page title or a revID?
2. Is it referring to revID=2016, ignoring title, as practised when both oldid= and title= provided in URL?

Does the {} syntax impose that revID may follow a title only, or title is optional? Curly brackets are not nested here. If each optional, #1 is ambiguous.

If there is no revision ID available for a particular page, is it supposed that the query is invalid? What about case #2?

In the page title, the forward slash (/) needs to be url encoded as %2F.

So, /User_talk:ltu%2FArchiv%2F2016/{revid}

Yeah, but this should be clarified.

Another issue is still ambiguos.

• API REST (v1) is currently the one and only REST API documentation.
• Parsoid/API tells us that v1 and v2 are deprecated and recommends v3.
• However, v1 says:
  /transform/wikitext/to/lint{/title}{/revision}
• The brackets must be nested, showing that requesting revID requires title:
  /transform/wikitext/to/lint{/title{/revision}}
• The brackets seem to indicate optional components; if revID is omitted, I might omit title as well. Syntax description does not explain whether title might be empty, but page could be identified by revID anyway.

Same lack of clarity for v3 syntax descriptions on dealing with optional and mandatory components.

• /transform/section-changes/to/wikitext/{title}/{revision} is less ambiguous. It suggests that I could omit either {title} or {revision}; if both than I did not specify the page of desire. Slash is to be kept and should follow a title anyway, it says.

The formal language of these syntax descriptions is undiscoverable, and dealing with mandatory and optional components or empty values isn't explained for v3 either.

BTW, v1 is told to be deprecated, but there is no syntax explained for title/revID LINT specification per v3. Might be POST payload method only, with unknown parameters in JSON, or could still be GET-like in v1 style, as /:domain/v3/transform/:from/to/:format/:title?/:revision? (why POST only?)

> Yeah, but this should be clarified.

It says, "Page title -- needs to be urlencoded (percent encoded)." I guess an example would help.

An easy way to see what constitutes the title is using querystring parameters, like,

https://en.wikipedia.org/w/index.php?title=User:Arlolra/sandbox

Here, the forward slash is clearly not part of the path.

> However, v1 says ...

The page under discussion is for the Parsoid API, which is similar (for some endpoints) but not the same as the REST API (from RESTBase). Let's concentrate on the former. Parsoid had two previous http api versions, but those were removed. Only v3 remains.

A title is optional if arbitrary wikitext is submitted, for the endpoint in question. However, if one wishes to supply a revision in the path, a title would be required. In other words, .../format//revision would be rejected. This is the semantics of your nested brackets above. I agree, the documentation around these parameters can be improved.

However, the Parsoid API is not exposed to external clients on the WMF production cluster. All requests go through RESTBase to Parsoid, and clients hitting /api/rest_v1/ should follow the REST API documents linked to above.