API:REST API

From MediaWiki.org
Jump to navigation Jump to search

The MediaWiki REST API lets you build apps and scripts that interact with wiki content. Like most web APIs, the MediaWiki REST API accepts HTTP requests at unique URLs and returns structured data.

Endpoints[edit]

Available in MediaWiki 1.35 and later:

  • History: Explore page history, compare revisions.

Data format[edit]

The REST API returns all data as JSON.

Methods[edit]

The REST API supports standard HTTP request methods like GET, HEAD, POST, and DELETE.

URL structure[edit]

API endpoints share a consistent URL structure that includes the wiki's base URL, the wiki's install path, and the API version.

# URL structure
[project url]/[install path]/rest.php/v[version number]/

# Example URL: Get the history of the Main Page of English Wikipedia
https://en.wikipedia.org/w/rest.php/v1/page/Main_Page/history

Versioning[edit]

Designed to provide long-term stability for developers, the MediaWiki REST API is versioned using a global version number in the API path (for example: /v1/). Following the principles of semantic versioning, the version is incremented when an endpoint is changed in a backwards-incompatible way, such as removing a response property or adding a required parameter. Within a major version, the API may change in backwards-compatible ways, such as adding a response property or optional request parameter.

/v1/ (latest) Available in MediaWiki 1.35

Accessing Wikimedia projects using the REST API[edit]

You can use the REST API to access Wikipedia, Wiktionary, and other Wikimedia projects in multiple languages. For a complete list of Wikimedia project URLs, see Meta-Wiki’s site matrix.

Get the history of the main page of Spanish Wikipedia https://es.wikipedia.org/w/rest.php/v1/page/Wikipedia:Portada/history
Get the number of revisions to the main page of Vietnamese Wiktionary https://vi.wiktionary.org/w/rest.php/v1/page/Trang_Ch%C3%ADnh/history/counts/edits

Request limit[edit]

There is no fixed limit on requests to the API, but your client may be blocked if you endanger the stability of a site. To stay within a safe request rate, make requests in series instead of in parallel by waiting for one request to finish before sending a new request.

Client identification[edit]

Wikimedia sites require an HTTP User-Agent header for all API requests. This helps identify your app and ensures that system administrators can contact you if a problem arises. Clients making requests without a User-Agent header may be IP-blocked without notice.

The preferred format for a User-Agent header is <client name>/<version> (<contact information>) <library/framework name>/<version>. Contact information can include a user page on the local wiki, a user page on a related wiki using interwiki linking syntax, a URL for a relevant external website, or an email address. For example, to set a User-Agent header in PHP:

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');

If you are calling the API from browser-based JavaScript, you may not be able to influence the User-Agent header, depending on the browser. To work around this, use the Api-User-Agent header. See Meta-Wiki’s User-Agent policy for more information.

Authorization[edit]

To authorize your app to act on behalf of a user, follow the OAuth developer guide to register your app and make requests using OAuth tokens.

Licensing and trademarks[edit]

Wikimedia content is free to reuse within the terms specified by the applicable license. Licenses can differ between projects, so see the individual project for information about licenses and content reuse. For example, English Wikipedia’s text can be used under the terms of the Creative Commons Attribution Share-Alike license, while media files on Wikimedia Commons are licensed individually as indicated on the file’s information page. For more information about licensing and trademark use, see Meta-Wiki’s developer app guidelines.

Enabling the REST API on your wiki[edit]

The REST API is available in MediaWiki 1.34 and later as disabled by default. To enable the REST API on your wiki, add $wgEnableRestAPI = true; to LocalSettings.php .

Extension endpoints[edit]

MediaWiki extensions can surface extension-specific API endpoints using the REST API interface. See the REST API extension interface docs to get started. For documentation for REST API endpoints provided by extensions, see the extension docs. The REST API extension interface is available in MediaWiki 1.34 and later.

Other APIs[edit]

There are two families of REST APIs related to Wikimedia projects: the MediaWiki REST API described on this page and the REST API built on RESTBase. While the MediaWiki REST API is part of the MediaWiki platform and can be enabled on any wiki running MediaWiki 1.34 or later, the RESTBase API serves content specific to Wikimedia projects. If you're looking for the full-featured, RPC-style MediaWiki API, see the Action API.

See also[edit]