API:REST API/History API

From MediaWiki.org
Jump to navigation Jump to search

The history API provides access to the revision history of a wiki page. You can use the history API to explore recent edits to a page, see metadata for a specific revision, compare versions, and get statistics about the history of a page. The history API is available in MediaWiki 1.35 and later.

MediaWiki version: 1.35

Exploring page history[edit]

A wiki page's history is divided into a sequence of revisions. A revision can be any change to the content of a page: an anonymous editor correcting a typo, an admin reverting vandalism, a bot fixing a citation link. The history API lets you browse through a page's history in segments of 20 revisions.

To see the 20 most recent revisions to a page, make a request to the page history endpoint, including the page title in the path. The page history endpoint returns the latest revision segment, starting with the most recent revision. Each revision object includes the revision ID, which you can use with the get revision and compare revisions endpoints. Revision IDs do not increase sequentially, so you may see an older revision with a higher revision ID than a newer revision.

$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history

Let's say we want to look further back in the history of the page. You can use the older URL from the response above to fetch the next 20 oldest revisions, not including the revision specified by the older_than parameter.

$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history?older_than=196313

In this example, the API does not return a new older URL, indicating that there are no older revisions left to return. Following the same pattern, the absence of a newer URL indicates that there are no newer revisions available.

From here, you can use the newer URL to scroll forward in the page's history, or, by requesting the page history without an older_than or newer_than parameter, return to the most recent revisions. Remember, the page history endpoint can only return up to 20 revisions, so you cannot use both the older_than and newer_than parameters in the same request.

To get information about a revision, use the revision ID to make a request to the revision endpoint.

$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/revision/95824/bare

Filtering page history[edit]

Some revisions are tagged to indicate the type of edit. The page history endpoint supports filtering by edit type, allowing you to request, for example, only edits made by bots or only edits made by anonymous users. See the endpoint reference for the complete list of supported filters.

To see the most recent edits made by bots, call the page history endpoint with the filter query parameter set to bot.

$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history?filter=bot

You can pair the filter parameter with the older_than or newer_than parameters to explore page history by revision type. Due to differences in caching infrastructure, the number of revisions returned by the page history filters may not match the statistics returns by the page history counts endpoint.

Comparing revisions[edit]

When exploring a page's history, you can use the size and delta to understand the impact of the edit in relation to the previous edit. You can also compare any two revisions line by line using the compare revisions endpoint. The compare revision endpoint takes two revision IDs as path parameters; you can use the page history endpoint to select revision IDs.

To compare revision 388863 to revision 388864, supply the revision IDs in the endpoint path. The API returns a JSON-formatted diff object comparing the two revisions.

$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/revision/388863/compare/388864

Page endpoints[edit]

Get page history[edit]

Route /page/{title}/history
Method GET

Returns information about the 20 latest revisions to a wiki page, starting with the latest revision. The returned revision segment includes API routes for the next oldest, next newest, and latest revisions, letting you scroll through page history. This endpoint responds to the presence a logged-in user and displays content appropriate to that user's permissions.

Request examples[edit]

# Get the latest 20 revisions of a page
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history

# Get the 20 revisions made by anonymous users prior to revision 196313
$ curl "https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history?filter=anonymous&older_than=196313"

Request parameters[edit]

parameter required example description
title required My_Wiki_Page The title of the wiki page being accessed
older_than optional 7153346 Accepts a revision ID. Returns the next 20 revisions older than the given revision ID.
newer_than optional 1420242 Accepts a revision ID. Returns the next 20 revisions newer than the given revision ID.
filter optional reverted Filters let you see only revisions with certain tags.

Available filters:

  • reverted: Returns only revisions that revert an earlier edit
  • anonymous: Returns only revisions made by anonymous users
  • bot: Returns only revisions made by bots
  • minor: Returns only revisions marked as minor edits

Responses[edit]

200 Success
400 Revision ID must be greater than 0
400 Parameters older_than and newer_than cannot both be specified
400 Invalid parameter
403 Permission denied
404 Title not found
404 Revision does not exist for the specified page

Response schema[edit]

property type description
latest

required

string The API route to get the 20 latest revisions
older

optional

string If available, the API route to get the 20 prior revisions.
newer

optional

string If available, the API route to get the 20 following revisions.
revisions

required

array Array of 0-20 objects representing a revision to the page, including:
  • id (integer): The revision ID. You can use this ID to compare revisions or get revision.
  • timestamp (string): The time of the edit in ISO 8601 format. (Example: 2019-03-24T16:37:55Z)
  • minor (boolean): Set to true for edits marked as minor
  • size (integer): The size of the edit in bytes.
  • comment (string): A comment or edit summary written by the editor. For revisions without a comment, the API can return null or "".
  • delta (integer): The change, positive or negative, in bytes between a revision and the preceding revision. If the preceding revision is unavailable, the API returns null. (Example: -20)
  • user (object): The name and id of the account that made the edit. For anonymous users, the name contains the originating IP address, and the id is null.

If no revisions are found, the API returns an empty array.

Get page history counts[edit]

Route /page/{title}/history/counts/{type}
Method GET

Returns data about a page's history.

Request examples[edit]

# Get the total number of users or bots that have edited a page
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history/counts/editors

# Get the number of edits made by anonymous users
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history/counts/anonymous

# Get the number of edits to a page between revisions 196313 and 388866
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/page/Main_Page/history/counts/edits?from=196313&to=388866

Request parameters[edit]

parameter required example description
title required My_Wiki_Page The title of the wiki page being accessed
type required edits The type of count.

Available types:

  • anonymous: Edits made by anonymous users
  • bot: Edits made by bots
  • editors: Users or bots that have edited a page
  • edits: Any change to page content
  • reverted: Edits that revert an earlier edit
  • minor: Edits marked as minor
from optional 196313 Restricts the count to between two revisions, specified by revision ID. The from and to query parameters must be used as a pair and can only be used with the edits and editors types. The result excludes the edits or editors represented by the from and to revisions.
to optional 388866

Responses[edit]

200 Success
200 Success - Count exceeds 1000
400 Invalid parameter
400 Invalid combination of parameters
403 Permission denied
404 Title not found
404 Revision not found
500 Minor edit count exceeds 2000

Response schema[edit]

property type description
count

required

integer The value of the data point up to 1000. If the value exceeds 1000, the API returns "count": 1000 and sets the limit property to true.
limit

required

boolean Set to true if the data point exceeds the limit of 1000.

Revision endpoints[edit]

Get revision[edit]

Route revision/{id}/bare
Method GET

Returns details for an individual revision. This endpoint responds to the presence a logged-in user and displays content appropriate to that user's permissions.

Request example[edit]

# See information for revision 726494
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/revision/95824/bare

Request parameters[edit]

parameter required example description
id required 95824 Revision ID

Responses[edit]

200 Success
403 Permission denied
404 Revision ID not found

Response schema[edit]

property type description
id

required

integer The revision ID
page

required

object The page_id and title of the page
user

required

object The name and id of the account that made the edit. For anonymous users, the name contains the originating IP address, and the id is null.
timestamp

required

string The time of the edit in ISO 8601 format. (Example: 2019-03-24T16:37:55Z)
comment

required

string A comment or edit summary written by the editor. For revisions without a comment, the API can return null or "".
size

required

integer The size of the edit in bytes.
delta

required

integer The change, positive or negative, in bytes between a revision and the preceding revision. If the preceding revision is unavailable, the API returns null. (Example: -20)
minor

required

boolean Set to true for edits marked as minor.

Compare revisions[edit]

Route revision/{from}/compare/{to}
Methods GET HEAD

Returns data that lets you display a line-by-line comparison of two revisions. (See an example.) Only text-based wiki pages can be compared; trying to compare revisions of other page types, such as image pages, results in a 400 response code. This endpoint responds to the presence a logged-in user and displays content appropriate to that user's permissions.

The compare revisions endpoint requires Wikidiff2 1.9.0 or later.

Request example[edit]

# Compare revision 388863 to 388864
$ curl https://en.wikipedia.beta.wmflabs.org/w/rest.php/v1/revision/388863/compare/388864

Request parameters[edit]

parameter required example description
from required 388863 Revision ID to use as the base for comparison
to required 388864 Revision ID to compare to the base

Responses[edit]

200 Success
400 Revision IDs are for different pages or for pages that can't be compared.
400 Invalid content type
403 Revision not publicly accessible
403 Permission denied
404 Revision ID not found
500 Wikidiff2 extension 1.9.0 or later not installed

Response schema[edit]

property type description
from

required

object Information about the base revision used in the comparison, including:
  • The revision id
  • The slot_role, usually main
to

required

object Information about the revision being compared to the base revision, including:
  • The revision id
  • The slot_role, usually main
diff

required

array of objects Each object in the diff array represents a line in a visual, line-by-line comparison between the two revisions.
diff.type

required

integer The type of change represented by the diff object, either:
  • 0: A line with the same content in both revisions, included to provide context when viewing the diff. The API returns up to two context lines around each change.
  • 1: A line included in the to revision but not in the from revision.
  • 2: A line included in the from revision but not in the to revision.
  • 3: A line containing text that differs between the two revisions. (For changes to paragraph location as well as content, see type 5.)
  • 4: When a paragraph's location differs between the two revisions, a type 4 object represents the location in the from revision.
  • 5: When a paragraph's location differs between the two revisions, a type 5 object represents the location in the to revision. This type can also include word-level differences between the two revisions.
diff.lineNumber

optional

integer The line number of the change based on the to revision.
diff.text

required

string The text of the line, including content from both revisions. For a line containing text that differs between the two revisions, you can use highlightRanges to visually indicate added and removed text. For a line containing a new line, the API returns the text as "" (empty string).
diff.highlightRanges

optional

array of objects An array of objects that indicate where and in what style text should be highlighted to visually represent changes.

Each object includes:

  • start (integer): Where the highlighted text should start, in the number of bytes from the beginning of the line.
  • length (integer): The length of the highlighted section, in bytes.
  • type (integer): The type of highlight:
    • 0 indicates an addition.
    • 1 indicates a deletion.
diff.moveInfo

optional

object Visual indicators to use when a paragraph's location differs between the two revisions. moveInfo objects occur in pairs within the diff.
  • id (string): The ID of the paragraph described by the diff object.
  • linkId (string): The ID of the corresponding paragraph.
    • For type 4 diff objects, linkId represents the location in the to revision.
    • For type 5 diff objects, linkId represents the location in the from revision.
  • linkDirection (integer): A visual indicator of the relationship between the two locations. You can use this property to display an arrow icon within the diff.
    • 0 indicates that the linkId paragraph is lower on the page than the id paragraph.
    • 1 indicates that the linkId paragraph is higher on the page than the id paragraph.
diff.sectionTitleIndex

optional

integer An integer referring to the section title of the change as listed in sectionTitles. For example: a value of 0 corresponds to the first title listed in the sectionTitles array; a value of 1 corresponds to the second title.
sectionTitles

optional

array of strings An array of section titles referenced in the diff.