API:Етикет

This page is a translated version of the page API:Etiquette and the translation is 27% complete.

Ця сторінка є частиною документації по MediaWiki Action API.

This page in a nutshell:

Set an informative User-Agent string with contact information, or you may be IP-blocked without notice. See the User-Agent policy for more details.
Make your requests in series rather than in parallel, by waiting for one request to finish before sending a new request.
Perform grouped updates via one single editEntity, for all languages and for labels, descriptions, and aliases at once.
On Wikimedia wikis, there may be faster ways to get bulk data. See m:Research:Data and wikitech:Portal:Data Services for more details.
See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

This page contains the best practices that should be followed when using the API. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

Поведінка

Обмеження запиту

There is no hard speed limit on read requests, but be considerate and try not to take a site down. Most system administrators reserve the right to unceremoniously block you if you do endanger the stability of their site.

Making your requests in series rather than in parallel, by waiting for one request to finish before sending a new request, should result in a safe request rate. It is also recommended that you ask for multiple items in one request by:

Using the pipe character (|) whenever possible e.g. titles=PageA|PageB|PageC, instead of making a new request for each title.

Using a generator instead of making a request for each result from another request.

Use GZip compression when making API calls by setting Accept-Encoding: gzip to reduce bandwidth usage.

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.

api.php?action=query&format=json&meta=userinfo&uiprop=ratelimits [спробуйте в ApiSandbox]

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.

Обробка версій сторінок парсером

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:

api.php?action=parse&format=json&prop=images&oldid=254862759 [спробуйте в ApiSandbox]

Параметр maxlag

Якщо ваше завдання не інтерактивне, тобто користувач не чекає результату, треба скористатися параметром maxlag. Значення параметра maxlag має бути цілим числом секунд. Наприклад:

api.php?action=query&format=json&titles=Main%20Page&maxlag=1 [спробуйте в ApiSandbox]

Це запобігатиме виконанню вашого завдання, коли навантаження на сервери велике. Вищі значення означають більш агресивну поведінку, нижчі значення – прийнятну.

Див. Посібник:Параметр Maxlag для докладнішої інформації.

Заголовок User-Agent

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.

See User-Agent policy for more details.

Формати даних

All new API users should use JSON . See API:Формати даних for more details.

Продуктивність

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:Головна сторінка - The quick start guide.
API:Ratelimit & API:Ratelimit/Wikimedia sites

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