Change Details

`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?

`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 [[ https://phabricator.wikimedia.org/source/mediawiki/browse/master/includes/api/ApiEditPage.php | 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.

`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 getAllowedParamStudy the [[ https://phabricator.wikimedia.org/source/mediawiki/browse/master/includes/api/ApiEditPage.php | source ]] to determine the range of outputs. == Potential result values * `redirects`: list of, (TODO explain the "redirect" param and what results mean.) 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 (missingabsent 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 (missingabsent otherwise). ** `oldrevid`: TODOPrevious revision's numeric ID. Absent if there was no change created. ** `newrevid`: TODONewly 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. == 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.Response data for other APIs * `apierror-missingtitle`: Would have to create a missing articleIn 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, but trying to exclusively editand then integrated with the source code and samples. * `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?