Page MenuHomePhabricator

Document return values for action=edit API
Open, Needs TriagePublic

Description

action=edit is at the heart of what we're asking of the Internet, yet the API documentation is minimalist. Starting with one concrete improvement, let's explain the possible result values and their structure. Study the source to determine the range of outputs.

Potential result values

  • redirects: list of redirects created (TODO: how can more than one be created? With batched params??). Each list item has from and to element:
    • from: source page title
    • to: target page title
  • edit: module result container
    • result: one of,
      • "Failure"
      • "Success"
    • new: Boolean true if this edit created a new page (absent otherwise).
    • pageid: Edited page's numeric ID.
    • title: Page title
    • contentmodel: Content model name, e.g. "wikitext".
    • nochange: Boolean true if no new revision was created (absent otherwise).
    • oldrevid: Previous revision's numeric ID. Absent if there was no change created.
    • newrevid: Newly created revision's numeric ID. Absent if there was no change created.
    • newtimestamp: New page last modified time, as ISO 8601 timestamp. Absent if there was no change created.

Extensions can add to the result and its structure! Those should be documented in a similar way, that can be included in the builtin help.

Response data for other APIs

In general, this is an under-documented aspect of our API. Return data should be documented for all API methods, even if it's just to explicitly say "returns no data". In future work, we could standardize result documentation to encourage adoption, like we do with overridden getAllowedParams. The work should be done on-wiki at first, and then integrated with the source code and samples.

Event Timeline

awight created this task.Aug 28 2018, 9:05 PM
awight updated the task description. (Show Details)Aug 28 2018, 9:29 PM
Anomie triaged this task as Lowest priority.Aug 29 2018, 2:05 PM
Anomie moved this task from Unsorted to Needs details or plan on the MediaWiki-API board.

This is a much harder problem than it at first seems.

At one point the API did try to include some specification of response format and list of errors. These were removed in 2014 (f0a6435f3) since the format for the former was never documented (and was implemented inconsistently), neither were kept up to date, and it was doubtful whether either could be kept up to date in the face of errors thrown from underlying business-logic code and changes made by extension hooks.

If someone wants to try implementing this it'll need to be done in a way that's clearly specified and is reasonable for people to keep up to date. And it'll need to be done in a way that could be applicable to all modules, not as an ad hoc hack for just action=edit.

It seems to me that a solution for the "user guide" on-wiki would be more likely to be successful than trying to do it in the API code itself.

Adding @srishakatux, as a subscriber. We're currently working on improving on-wiki documentation for the API, and this may be relevant.

srodlund raised the priority of this task from Lowest to Needs Triage.Aug 29 2018, 6:48 PM
srodlund moved this task from Backlog to API Documentation Request on the Documentation board.
Restricted Application added a project: Core Platform Team. · View Herald TranscriptOct 27 2019, 8:17 AM

@awight I am an Outreachy applicant working on this task. Please I need some clarification. Am I to document only what has been listed as TODO?

@awight I am an Outreachy applicant working on this task.

Hi, that's great news. Thank you for putting time into this work!

Please I need some clarification. Am I to document only what has been listed as TODO?

No, sorry for the confusion. The "TODO" notes were to indicate that the task isn't fully defined, but at this point I think it makes sense to include the TODOs in the work itself, I'll take a pass at cleaning up the task description.

The situation as I understand it is that action=edit has no documentation of its response structure. Checking the built-in API documentation and the wiki page, I wouldn't know to expect an oldrevid after every edit for example, or what to do with it, or what it will contain if this is the first revision of an article. This could be a bigger deal than it looks like, note Anomie's point in T203025#4542344 that we don't have a standard way to document response structure for the built-in API docs, and maybe not even for the wiki docs.

Happily, it looks like the errors are already documented on-wiki, just not in the source code.

On that note, I assume that the scope of the Outreachy project T232816 is to update the wiki docs first, but built-in docs would fall under the "OPTIONAL" note about editing sample code or even in later follow-up work?

awight updated the task description. (Show Details)Oct 28 2019, 12:09 PM

Thank you @awight . I will start from documenting the possible result values and their structure for the API:Edit wiki page first.

When a user is editing a redirect page and wants to create a new section in the target page. The first redirect is the target page and the second is the new section created in this target page. So you have section=new.
@awight Please is that how action=Edit API creates redirects using batched params. Please could you clarify me.

When a user is editing a redirect page and wants to create a new section in the target page. The first redirect is the target page and the second is the new section created in this target page. So you have section=new.
@awight Please is that how action=Edit API creates redirects using batched params. Please could you clarify me.

Good question. Looking more closely, I think that the Edit API only supports a single edit, so there is no "batch" mode like I was hypothesizing yesterday. In case it helps, here's the source code I'm reading from: https://phabricator.wikimedia.org/source/mediawiki/browse/master/includes/api/ApiEditPage.php . Your understanding of the logic sounds better than mine, but I'll try to paraphrase what I see in the code just in case it helps us both:

The redirects output field is only populated when the redirect input parameter is passed. redirect can only be passed when prepending or appending a section=new. When the page being edited is a redirect, and the redirect parameter was set, then we resolve the title to its target. This shows up as "from" and "to" in the first item of the redirects output list. Although double (and more) redirects are not supposed to work, we still seem to support them here, and these additional redirects will be returns as successive elements in the output redirects list.

Very strange feature, but at leasts it starts to make sense.

Thank you @awight it looks clearer to me now.