API:礼仪
| 本页是MediaWiki Action API帮助文档的一部份。 |
本頁簡而言之：
|
本页面教你使用 API 时都有哪些事情应当注意。 See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.
行为规范
请求限制
读取请求没有速率限制或者什么苛刻的条件，但是体谅一点，不要让站点访问速度变慢。 如果你威胁到站点的安全，多数管理员保留将你封禁的权力。
要一次一次地发送请求，而不是一次发送多个请求。前一个请求完成了再发送下一个请求，这样请求速率会较安全。 如果你要操作多个项目，应该遵守以下条件：
- 只要能用管道符号（
|）就不要给每个标题都创建一个新的请求。例：titles=PageA|PageB|PageC
- Using a generator instead of making a request for each result from another request.
- 进行 API 调用时使用 GZip 压缩减少带宽消耗。
Requests which make edits, modify state or otherwise are not read-only requests, are subject to rate limiting. The exact rate limit being applied might depend on the type of action, your user rights and the configuration of the website you are making the request to. The limits that apply to you can be determined by accessing the action=query&meta=userinfo&uiprop=ratelimits API endpoint.
When you hit the request rate limit you will receive a API error response with the error code ratelimited. When you encounter this error, you may retry that request, however you should increase the time between subsequent requests. A common strategy for this is Exponential backoff.
Parsing of revisions
While it is possible to query for results from a specific revision number using the revid parameter, this is an expensive operation for the servers.
To retrieve a specific revision use the oldid parameter. For example:
The maxlag parameter
If your task is not interactive, i.e. a user is not waiting for the result, you should use the maxlag parameter.
The value of the maxlag parameter should be an integer number of seconds.
例如：
This will prevent your task from running when the load on the servers is high. Higher values mean more aggressive behavior, lower values are nicer.
要了解更多详情，请参见手册:Maxlag参数。
The User-Agent header
It is best practice to set a descriptive User Agent header.
To do so, use User-Agent: clientname/version (contact information e.g. username, email) framework/version....
For example in PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Do not simply copy the user-agent of a popular web browser. This ensures that if a problem does arise it is easy to track down where it originates.
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.
要了解更多详情，请参见用户代理方针。
数据格式
所有新的API用户应使用JSON。 有关更多详细信息，请参见API:数据格式。
性能
Downloading data in bulk is not always extremely efficient using the Action API. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.
Other notes
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.
Whenever you're reading data from the web service API, you should try to use GET requests if possible, not POST, as the latter are not cacheable and, in multi-datacenter configurations (including Wikimedia sites), may go to a farther data center.
In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see 工單T91820.
参见
- Official guidelines about API usage on Wikimedia Foundation Governance wiki
- API:首页 - 快速入门指南。
- API:Ratelimit & API:Ratelimit/Wikimedia sites
- Maintained by MediaWiki Interfaces Team.
- Live chat (IRC): #mediawiki-core 連線
- Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)