User:APaskulin (WMF)/Sandbox/Overview

The REST API lets you interact with MediaWiki by sending HTTP requests to unique URLs. You can use the API to build apps and scripts that search wiki pages and explore page history.

Documentation

Tutorials

Community

Data formats edit

Each API endpoint supports a single data format: either JSON or HTML. See the API reference for the content type supported by each endpoint.

Methods edit

The API supports standard HTTP request methods.

GET	Retrieve resource
HEAD	Return HTTP headers for a GET request without response data
POST	Create resource
PUT	Update or create resource

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. To learn about API versioning, see the stability policy.

# URL structure
[base 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

Permissions and authorization edit

The REST API is designed to be used with the OAuth extension for user authentication and authorization. However, regardless of the authentication method, the API responds to the presence of a logged-in user and returns content appropriate to that user's permissions.

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.

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, wait for each request to finish before sending another 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 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.

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.

Other APIs edit

API	Availability	URL base	Example
MediaWiki REST API	Included with MediaWiki 1.35+ (disabled by default) Enabled on Wikimedia projects	/rest.php	https://en.wikipedia.org/w/rest.php/v1/page/Earth
MediaWiki Action API	Included with MediaWiki (enabled by default) Enabled on Wikimedia projects	/api.php	https://en.wikipedia.org/w/api.php?action=query&prop=info&titles=Earth
Wikimedia REST API	Not included with MediaWiki Available for Wikimedia projects only	/api/rest	https://en.wikipedia.org/api/rest_v1/page/title/Earth

About these docs edit

These docs are written manually based on the MediaWiki Core source code. Corrections and additions are welcome! To share a tutorial or app that uses the MediaWiki REST API, add a link to the REST API template.