API:Main page/zh

 MediaWiki现有三种接口：
 * MediaWiki API，提供对wiki功能、数据和元数据便利的访问，本文是API的概述.
 * Special:Export页面，提供将wiki内容批量导出为XML的功能，请参阅meta.wikimedia.org上的导出功能帮助.
 * 标准web界面（您现在应该就正在使用），请参阅Manual:Parameters to index.php以了解使用web界面的信息.

您可能在寻找用于内部扩展的接口，它使得PHP开发者向安装的MediaWiki添加新功能.

'''这是一个概述性的总览，请点击右边的导航查看更详细的信息. '''

如果您希望监视一个MediaWiki安装，或是创建一个机器人来自动维护它，您可以使用MediaWiki的web服务API. Web服务API提供了直接、高级的方式来访问MediaWiki里的数据. 客户端程序向其可以自动登录、获取数据、提交修改等. 它可以支持机器人，轻量级基于web的JavaScript客户端，如导航popups和LiveRC等，普通的应用程序，如vandal fighter，或是其他网站（Toolserver上的实用程序）.

新安装的MediaWiki中，此web服务默认启用，但管理员可以把它禁用.

简单例子
这个URL让英文维基百科的web服务API向您传送首页的内容：

http://en.wikipedia.org/w/api.php?format=xml&action=query&titles=Main%20Page&prop=revisions&rvprop=content

用任意编程语言向这个URL发送一个HTTP GET请求（或直接在浏览器中打开这个链接），您便可得到一个XML文档，其中包含“Main Page”页面中当前的wiki代码. 这就是一个能运作的web服务API.

我们来分解这个URL，以展示它如何工作.

接入点
这就是接入点，就像MediaWiki的web服务API的首页. 这个URL是英文维基百科的API的基础URL，就像 是其网站的基础URL.

如果您写一个使用英文维基百科的程序，每一个您需要构造的URL都以这个基础URL开头. 如果您在其他MediaWiki系统上操作，您需要找到它的接入点，并相应地使用那个地址. 所有Wikimedia的wiki的接入点都符合这个模式：

http://en.wikipedia.org/w/api.php     # 英文维基百科API http://nl.wikipedia.org/w/api.php     # 荷兰语维基百科API http://commons.wikimedia.org/w/api.php # 维基共享资源API

下面我们来看看URL的查询字符串中的参数.

格式
这告诉Wikimedia的web服务API我们希望数据以XML格式返回. 这个API支持许多输出格式，包括JSON、WDDX、XML、YAML以及PHP的原生序列化格式.

动作
这是“动作”. MediaWiki的web服务API支持超过50种动作，并在API参考中均有说明. 在这个例子中，我们使用“query”来告诉API，我们希望获取一些数据.

“query”动作是API最重要的动作之一，并有它自己更多的文档. 下面只是这个例子的一些解释.

特定于动作的参数
示例URL的剩余部分包含“query”动作所需的参数. 这里，我们告诉web服务API我们需要关于“Main Page”这一wiki页面的信息. （%20来自空格的百分号编码）您可以一次请求多个页面：详见query文档.

这个参数告诉web服务API我们对这个页面的一个特定版本感兴趣. 因为我们没有指定任何版本信息，API会给我们最新版本的信息——维基百科现在正使用的首页.

最后，这个参数告诉web服务API我们需要这一页面的最新版本的内容. 如果我们传入 ，我们便能得到最新版本的内容以及创建了这一最新版本的用户的名称.

再说一次，这只是一个例子. 查询在这里有更详细的解释，同时API参考列出了所有可能的动作、所有 的可能取值、以及更多其他内容.

新手上路
Before you start using the MediaWiki web service API, be sure to read these documents:


 * The FAQ.
 * The page about input and output formats
 * The page about errors and warnings
 * Any policies that apply to the wiki you want to access, such as (for Wikimedia Foundation wikis) our terms of use. These terms apply to you when you access or edit using the web service API, just as they do when you use your web browser.

Beyond that point, what you need to read depends on what you want to do. The right-hand menu links to detailed, task-specific documentation, and some more general guidelines are given below.

标示您的客户端
When you make HTTP requests to the MediaWiki web service API, be sure to specify a  header that properly identifies your client. Don't use the default  provided by your client library, but make up a custom header that includes the name and the version number of your client: something like "MyCuteBot/0.1".

On Wikimedia wikis, if you don't supply a  header, or you supply an empty or generic one, your request will fail with an HTTP 403 error. See our User-Agent policy. Other MediaWiki installations may have similar policies.

If you are calling the API from browser-based JavaScript, you won't be able to influence the  header: the browser will use its own. There is currently no other mechanism for a browser-based client to identify itself.

登录
Your client will probably need to log in to MediaWiki, possibly via its own user account. See the login manual page for details.

让您的请求可缓存
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. If you make a request for, and cache the result, then a request for   will not go through the cache--even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.

资源列表
The menu bar on the right side of this page links to more detailed, task-specific documentation. Here are some links having to do with the API as a whole:


 * The API sandbox on English Wikipedia makes it easy to try out different actions interactively.
 * The API reference contains automatically-generated descriptions of all actions and parameters.
 * Hook into Wikipedia information using PHP and the MediaWiki API (IBM developerWorks article, 17 May 2011)
 * 用户提醒和提问的邮件列表：API邮件列表
 * 低流量的仅用于发布公告的邮件列表（这里的消息也会同步发送到mediawiki-api）：mediawiki-api-announce
 * 查询和提交API的bug：Bugzilla（当提交新bug时，不要忘记设置Component=API）
 * Browse the API source code in SVN
 * The current MediaWiki database schema
 * Browse the current database schema in SVN

存档

 * 2006年的API讨论