API:REST API

The MediaWiki REST API lets you interact with MediaWiki by sending HTTP requests to rest.php URLs. You can use the API to build apps and scripts that search and display wiki pages, get media files, and explore page history.

快速入门

# Search English Wikipedia for an article about Earth $ curl "https://en.wikipedia.org/w/rest.php/v1/search/page?q=earth&limit=1"

试试看

日期格式

REST API endpoints return data in JSON or HTML format. See the API reference for the content type supported by each endpoint.

Methods

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结构

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

# URL結構
[專案URL]/[腳本路徑]/rest.php/v[版本號]/

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

# ----

# URL结构
[项目URL]/[脚本路径]/rest.php/v[版本号]/

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

版本控制

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/ (最新版本)	Available in MediaWiki 1.35

权限和授权

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.

使用REST API访问维基媒体项目

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.

请求限制

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.

辨识客户端

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 User-Agent header 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.

# Preferred format for User-Agent headers
<-{zh-hans:客户端名; zh-hant:用戶端名稱;}->/<版本> (<-{zh-hans:联系信息; zh-hant:聯絡資訊;}->) <library/framework name>/<版本>

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 the User-Agent policy for more information.

授权

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

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.

Limitations on Wikidata

While the REST API is available on Wikimedia projects, it is not fully supported by Wikidata. As of writing, some of the endpoints may return unexpected errors. Instead, use the Wikidata REST API.

Extension endpoints

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 via $wgEnableRestAPI and in MediaWiki 1.35 and later by default.

API比较

API	可用情况	根URL	示例
MediaWiki Action API	随附于MediaWiki 启用于维基媒体项目	/api.php	https://en.wikipedia.org/w/api.php?action=query&prop=info&titles=Earth
MediaWiki REST API	随附于MediaWiki 1.35+ 启用于维基媒体项目	/rest.php	https://en.wikipedia.org/w/rest.php/v1/page/Earth
Wikimedia REST API	不随附于MediaWiki 仅能用于维基媒体项目	/api/rest	https://en.wikipedia.org/api/rest_v1/page/title/Earth
有关维基媒体项目的商业规模API，请参阅Wikimedia Enterprise

关于帮助文档

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.

参阅

• REST API on Wikipedia
• REST API initiative page
• Manual:$wgRestPath

• Maintained by MediaWiki Interfaces Team.
• Live chat (IRC): #mediawiki-core ^連線
• Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)