API:Rollback/sd

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Rollback and the translation is 5% complete.

Other languages:
Deutsch • ‎English • ‎dansk • ‎español • ‎français • ‎română • ‎sicilianu • ‎русский • ‎العربية • ‎سنڌي • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
MediaWiki version: 1.12

POST request to revert the last series of edits made by one user to a given page.

This functionality is identical to the one provided by the rollback links in the graphical interface on history page.

API documentation




action=rollback

(main | rollback)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

Undo the last edit to the page.

If the last user who edited the page made multiple edits in a row, they will all be rolled back.

Parameters:
title

Title of the page to roll back. Cannot be used together with pageid.

pageid

Page ID of the page to roll back. Cannot be used together with title.

Type: integer
tags

Tags to apply to the rollback.

Values (separate with | or alternative):
user

Name of the user whose edits are to be rolled back.

This parameter is required.
Type: user name
summary

Custom edit summary. If empty, default summary will be used.

Default: (empty)
markbot

Mark the reverted edits and the revert as bot edits.

Type: boolean (details)
watchlist

Unconditionally add or remove the page from the current user's watchlist, use preferences or do not change watch.

One of the following values: watch, unwatch, preferences, nochange
Default: preferences
token

A "rollback" token retrieved from action=query&meta=tokens

For compatibility, the token used in the web UI is also accepted.

This parameter is required.
Examples:
Roll back the last edits to page Main Page by user Example.
api.php?action=rollback&title=Main%20Page&user=Example&token=123ABC [open in sandbox]
Roll back the last edits to page Main Page by IP user 192.0.2.5 with summary Reverting vandalism, and mark those edits and the revert as bot edits.
api.php?action=rollback&title=Main%20Page&user=192.0.2.5&token=123ABC&summary=Reverting%20vandalism&markbot=1 [open in sandbox]

Example

Making any POST request is a multi-step process:

  1. Log in, via one of the methods described in API:Login .
  2. GET a CSRF token :
  3. Send a POST request, with the CSRF token, to take action on a page and in this process gain editpage rights to the given page:
  4. GET a rollback token:

POST request

Send a POST request, with a rollback token to revert a user's edits to the Sandbox page.

In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=rollback requires POST requests; GET requests will cause an error.

Response

The Response section below is for the final POST request, to revert the edits to the Sandbox page.

{
    "rollback": {
        "title": "Sandbox",
        "pageid": 94542,
        "summary": "Reverted edits by [[Special:Contributions/41.190.3.231|41.190.3.231]] ([[User talk:41.190.3.231|talk]]) to last revision by [[User:Didicodes|Didicodes]]",
        "revid": 381084,
        "old_revid": 381083,
        "last_revid": 381070
    }
}

Sample code

rollback.py

#!/usr/bin/python3

"""
    rollback.py

    MediaWiki Action API Code Samples
    Demo of `rollback` module: Sending post request to rollback the
    last edits made to a given page.

    MIT license
"""
import requests

S = requests.Session()

URL = "https://test.wikipedia.org/w/api.php"

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_1)
DATA = R.json()

LOGIN_TOKEN = DATA['query']['tokens']['logintoken']

# Step 2: Send a post request to login. Use of main account for login 
# is not supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & 
# lgpassword
PARAMS_2 = {
    "action": "login",
    "lgname": "bot_user_name",
    "lgpassword": "bot_password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

R = S.post(URL, data=PARAMS_2)

# Step 3: While logged in, retrieve a CSRF token
PARAMS_3 = {
    "action": "query",
    "meta": "tokens",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_3)
DATA = R.json()

CSRF_TOKEN = DATA["query"]["tokens"]["csrftoken"]

# Step 4: POST request to edit a page
PARAMS_4 = {
    "action": "edit",
    "title": "Sandbox",
    "token": CSRF_TOKEN,
    "format": "json",
    "appendtext": "Hello"
}

R = S.post(URL, data=PARAMS_4)

# Step 5: Retrieve a rollback token
PARAMS_5 = {
    "action": "query",
    "meta": "tokens",
    "type": "rollback",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_5)
DATA = R.json()

ROLLBACK_TOKEN = DATA['query']['tokens']['rollbacktoken']

# Step 5: POST request to rollback a page. Grant your bot the rights to
# rollback pages via Special:BotPasswords.
PARAMS_6 = {
    "action": "rollback",
    "format": "json",
    "title": "Sandbox",
    "user": "bot_user_name",
    "token": ROLLBACK_TOKEN,
}

R = S.post(URL, data=PARAMS_6)
DATA = R.json()

print(DATA)

Permissions

Rollback requires both the editpage and the rollback right on the target page; currently, this means that OAuth consumers, bot passwords etc. require both the editpage and the rollback grant – rollback alone is not enough!

Possible errors

In addition to the usual stuff:

ڪوڊ معلومات
alreadyrolled The page you tried to rollback was already rolled back
missingparams One of the parameters "title" and "pageid" is required.
mustpostparams The rollback module requires a POST request.
notitle The title parameter must be set.
notoken The token parameter must be set.
nouser The user parameter must be set.
onlyauthor The page you tried to rollback only has one author
permissiondenied The action you have requested is limited to users in one of the groups: Administrators, Rollbackers

Parameter history

  • v1.24: Introduced pageid
  • v1.27: Introduced tags
  • v1.17: Introduced watchlist

Additional notes

  • Optionally, both the rollback and the edits being rolled back can be marked as bot, which hides them from Special:RecentChanges by default.

See also