Page MenuHomePhabricator

Curator gets page history
Closed, ResolvedPublic

Description

"As a Curator, I want to get a list of the previous revisions of a page, so that I can understand how it developed over time."

GET /page/{title}/history?{older_than|newer_than={id}}

Segmented history of a page. (I'm calling it "segmented" instead of "paged" so we don't all go crazy.)

{title} is the page title.
If older_than is provided, only show the newest revisions strictly older than the given revision ID, non-inclusive.
If newer_than is provided, only show the oldest revisions strictly newer than the given revision ID, non-inclusive.
Only one of older_than or newer_than are allowed.

Request body: none

Notable request headers: none

Notable response headers: none

Body: JSON, an object with the following fields:
older: full link to API endpoint for the next older segment of results (usually the same endpoint plus "older_than" with the last revision in this segment). May be excluded if there are no known older revisions.
newer: full link to API endpoint for the next newer segment of results (usually the same endpoint plus "newer_than" parameter for first revision in this segment). May be excluded if there are no known older revisions.
latest: full link to API endpoint for the latest values, usually just this endpoint with no parameters
revisions: an array of 0 to 20 revision objects, each with the following information:
id: revision id
comment: edit summary of the change, provided by the user
timestamp: date of change, YYYY-MM-DDTHH:MM:SSZ
delta: +/- count of bytes changed from previous
size: count of bytes
user: user who made the change, object with {id, name}

Event Timeline

There are some assumptions in here:

  • Segmentation is done relative to boundary versions rather than providing a "page=N" parameter. Those are notoriously difficult to work with when new versions can be added at any time. Although we do have deletions and undeletions of versions, "older_than={id}" should give about the same results each time.
  • There's a fixed segment size of 20 versions. I'd rather not deal with having it variable unless the iOS client requires that.

One thing I want to confirm; it's possible for administrators to delete revisions (usually only done for copyright violations, abusive content, etc.). I think they can review deleted revisions, but I don't think those deleted revisions appear in Action API results for admins.

All of which is to say, I don't think it's important to deal with authentication in this endpoint. There are some wikis that are protected for reads; I'd be happy to just throw an error in that case, and deal with authentication "later".

{title} is the page title.

Why are we keying the API on the page title instead of the page id? Was there any discussion to make this decision? Both page_id and page_title present their own pros and cons. Problem with using the "title" in this API, for example, would be page moves. What if the page was moved, would revisions belonging to the previous title be shown?

I removed the requirements around caching headers per discussion with @tstarling . We're going to skip these for now.

This is in integration tests, so I'm marking it done.