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.

This should be done for all API methods, even if it's just to say "returns no data" explicitly. In future work, we could standardize result documentation to encourage adoption, like we do with overridden getAllowedParams.

Potential result values

  • redirects: list of, (TODO explain the "redirect" param and what results mean.)
    • 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 (missing 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 (missing otherwise).
    • oldrevid: TODO
    • newrevid: TODO
    • newtimestamp: New page last modified time, as ISO 8601 timestamp.

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.

Potential errors

This section is a bit silly because the errors are already documented by translation strings, so we can already pull into the built-in API help.

  • hookaborted: Edit was cancelled by a APIEditBeforeSave hook.
  • apierror-blocked: Page edit blocked for user.
  • apierror-redirect-appendonly: TODO
  • apierror-no-direct-editing: This type of content cannot be edited directly by API.
  • apierror-badformat: (?) error where content format doesn't match the namespace.
  • apierror-articleexists: Article already exists, but we tried to exclusively create.
  • apierror-missingtitle: Would have to create a missing article, but trying to exclusively edit.
  • apierror-appendnotsupported: Content type has no support for appending.
  • apierror-sectionsnotsupported: Content type can't do requested section edit.
  • apierror-nosuchsection: Tried to edit a nonexistent section.
  • apierror-invalidsection: TODO
  • apierror-nosuchrevid: Tried to undo to nonexistent revision.
  • apierror-revwrongpage: Can't undo to revision on a different page.
  • undo-failure: Failed to undo.
  • apierror-badmd5: Content doesn't match checksum, likely corruption during the request.

TODO: There's a large dieStatus switch with dozens of cases, how are those returned?

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.

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.