REST: decide on a name for the module that will replace the Parsoid endpoints.
Open, In Progress, MediumPublic
Actions

Assigned To

None

Authored By

	daniel
	Tue, Jun 25, 9:17 PM

Description

We are planning to deprecate the Parsoid endpoints that are currently exposed through RESTbase (T334238). Clients should use the equivalent core endpoints instead. In order to support this, we want to make the URLs of the core endpoints more future proof.

Since the new URLs will use per-module versioning, we need to determin a module name to use for the new URLs of the core endpoints.

The old RESTbase endpoints are:

/api/rest_v1/page/title/{title}
/api/rest_v1/page/title/{title}/{revision}
/api/rest_v1/page/html/{title}
/api/rest_v1/page/html/{title}/{revision}

In RESTbase, these are defiend in the content module and tagged as "Page content".

The new endpoints will be exposed under:

/api/xxxxx.v1/page/{title}
/api/xxxxx.v1/page/{title}/with_html
/api/xxxxx.v1/page/{title}/html
/api/xxxxx.v1/page/{title}/bare
/api/xxxxx.v1/revision/{id}
/api/xxxxx.v1/revision/{id}/with_html
/api/xxxxx.v1/revision/{id}/html
/api/xxxxx.v1/revision/{id}/bare

These endpoints are functionally equivalent but structurally different. The endpoints for retrieving HTML without a JSON wrapper are nearly exactly the same, they only differ in the handling of wiki redirects. We also support POST and PUT for creating/updating pages:

POST /api/xxxxx.v1/page
PUT /api/xxxxx.v1/page/{title}

The purpose of this ticket is to decide what we want to replace the xxxxx part with. We could follow the example of RESTbase and use content.v1. Ir we could use pages.v1.

Nither option is idea. Some examples as food for thought:

/api/pages.v1/revision/{id}/bare (revision meta data, no content, nothign about the page)
/api/pages.v1/revision/{id}/html (revision HTML)
/api/content.v1/page/{title} (page meta-data and wikitext)
/api/content.v1/page/{title}/bare (page meta-data, no content)

Other options?

Related Objects

Mentioned Here: T334238: Create deprecation plan for public parsoid endpoints

Event Timeline

daniel created this task.Tue, Jun 25, 9:17 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptTue, Jun 25, 9:17 PM

For reference, here are some adjacent endpoints that are related to pages but do not correspond to the old parsoid endpoints:

/v1/page/{title}/history
/v1/page/{title}/history/counts/{type}
/v1/revision/{from}/compare/{to}
/v1/page/{title}/links/language
/v1/page/{title}/links/media
/v1/file/{title}

daniel updated the task description. (Show Details)Wed, Jun 26, 9:59 AM

daniel moved this task from Inbox, needs triage to MediaWiki Interfaces team on the MediaWiki-Engineering board.Wed, Jun 26, 1:31 PM

MSantos added a project: Content-Transform-Team.Wed, Jun 26, 1:43 PM

Good question. Not sure I have a great answer, but I do have a few thoughts.

First, we should probably agree on whether we care about singular or plural. That's something of a religious argument, and I don't have strong feelings. I'd just rather not go through that discussion every time naming comes up. We seem to be mostly using singular in core right now, although there's /v1/page/{title}/links/language, which is a cringey mix of conventions, and, and is handled by LanguageLinksHandler, whose name is backwards from the url. But anyway, a module name of pages wouldn't match the url path component of page. So if we go with plural, let's make sure we're doing it on purpose and plan to keep doing it.

Also, we have the general rule that "everything is a wiki page". As noted on the linked page, that's not strictly true, but "page" is our primary public-facing abstraction, and quite a lot falls under there. So a module name of "page" or "pages" covers a lot of territory. My concern is that it may cover so much that it becomes prohibitively painful to change the version number of whatever we call such a large module, and we end up right back in the situation where we don't actually do versioning. Of course, too granular is also bad, for different reasons. But "pages" seems pretty broad, and I'd lean away from that.

Of the proposals put forth so far, I'm more in favor of "content" than "pages". If I think of an alternative suggestion, I'll post it.

MSantos edited projects, added Content-Transform-Team-WIP; removed Content-Transform-Team.Thu, Jun 27, 2:04 PM

MSantos moved this task from Backlog to Needs Investigation on the Content-Transform-Team-WIP board.

BPirkle changed the task status from Open to In Progress.Thu, Jun 27, 3:17 PM

BPirkle triaged this task as Medium priority.

BPirkle moved this task from Incoming (Needs Triage) to In Progress on the MW-Interfaces-Team board.

I'm also +1 to content. Thanks for doing this!

+1 for content

REST: decide on a name for the module that will replace the Parsoid endpoints.Open, In Progress, MediumPublicActions

Description

Related Objects

Event Timeline

REST: decide on a name for the module that will replace the Parsoid endpoints.
Open, In Progress, MediumPublic
Actions