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,
- 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.
- result: one of,
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.
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?