API:Etiquette/ru

Эта страница содержит рекомендации, которые следует соблюдать при использовании API.

Поведение


Ограничение на запросы
Нет жёстко установленного ограничения на запросы чтения, но будьте учтивы и старайтесь не препятствовать работе сайта. Большинство системных администраторов оставляют за собой право заблокировать вас без предупреждения, если вы подвергаете угрозе стабильность их системы.

Выполнение ваших запросов последовательно, а не параллельно, с ожиданием завершения одного запроса перед отправкой нового запроса, должно обеспечить безопасную частоту запросов. Также рекомендуется запрашивать несколько элементов в одном запросе:


 * Используя символ вертикальной черты, когда это возможно, например, , вместо того, чтобы делать новый запрос для каждого заголовка.
 * Используя вместо выполнения запроса для каждого результата из другого запроса.


 * Используйте сжатие GZip при выполнении вызовов API, установив  для уменьшения использования полосы пропускания.

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 with the error code. 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.



Обработка версий страниц парсером
Хотя с помощью параметра  можно запрашивать результаты из определённого номера версии, для серверов эта операция является ресурсоёмкой. Чтобы получить конкретную версию, используйте параметр. Например:



Параметр maxlag
Если ваша задача не интерактивна (то есть нет пользователя, ждущего результата), следует использовать параметр. Значение параметра  должно быть целым числом секунд. Например:

Это позволит избежать выполнения вашей задачи при высокой нагрузке на серверах. Более высокие значения означают более агрессивное поведение, более низкие значения — более сдержанное.

См. для более детальной информации.



Заголовок User-Agent
Рекомендуется задать описательный заголовок User Agent. Для этого используйте. Например, в PHP:

Не стоит просто копировать user-agent из популярного веб-браузера. Это гарантирует, что при возникновении проблемы отследить её источник будет легко.

Если вы вызываете API из JavaScript на основе браузера, вы можете не иметь возможности влиять на заголовок, зависящий от браузера. Чтобы обойти это, используйте заголовок.

См. Политику User-Agent для подробностей.



Форматы данных
Все новые пользователи 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.

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.



См. также

 * - Краткое руководство по началу работы.