API:Этикет

Эта страница содержит рекомендации, которые следует соблюдать при использовании API. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

Поведение

Ограничение на запросы

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

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

• Используя символ вертикальной черты (|), когда это возможно, например, titles=PageA|PageB|PageC, вместо того, чтобы делать новый запрос для каждого заголовка.
• Используя генератор вместо выполнения запроса для каждого результата из другого запроса.

• Используйте сжатие GZip при выполнении вызовов API, установив Accept-Encoding: gzip для уменьшения использования полосы пропускания.

Запросы, которые вносят изменения, изменяют состояние или иным образом не являются запросами для чтения, подлежат ограничению по скорости. Точное применяемое ограничение скорости может зависеть от типа действия, ваших прав пользователя и настройки сайта, на который вы обращаетесь. Ограничения, которые применяются к вам, можно определить, посетив конечный пункт API action=query&meta=userinfo&uiprop=ratelimits.

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

Когда вы нажмете лимит запроса, вы получите API error response ответ на ошибку в API с кодом ошибки ratelimited. Если вы обнаружите эту ошибку, вы можете попробовать запрос снова, но вы должны увеличить время между последующими запросами. Общая стратегия для этого - Exponential backoff.

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

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

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

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

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');

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

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

См. подробнее в политике использования User-Agent (в Мета-вики).

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

Все новые пользователи API должны использовать JSON . См. API:Форматы данных с более подробной информацией.

Производительность

Массовая загрузка данных с использованием Action API не всегда очень эффективна. В вики-сайтах Викимедиа есть более быстрые способы получения больших массивов данных, см. более подробно в m:Research:Data и wikitech:Portal:Data Services.

Другие замечания

Если ваши запросы получают данные, которые можно кэшировать на некоторое время, вам следует предпринять шаги по их кэшированию, чтобы не запрашивать одни и те же данные снова и снова. Некоторые клиенты могут сами кэшировать данные, но для других (особенно клиентов JavaScript) это невозможно.

Всякий раз, когда вы читаете данные из API веб-сервиса, вам следует по возможности использовать запросы GET, а не POST, поскольку последние не кэшируются, а при использовании сервисом архитектуры сети с несколькими центрами обработки данных (как сервисы Викимедиа), могут быть отправлены в более отдалённый центр.

В исключительных случаях, когда вам действительно требуется использовать POST для запроса на чтение, например, при вызове action=parse с длинной строкой викиразметки, подумайте о том, чтобы установить заголовок Promise-Non-Write-API-Action: true. Это позволяет серверу приложений при необходимости обработать ваш POST-запрос в ближайшем центре обработки данных. Нет необходимости устанавливать этот заголовок для GET-запросов, его также не следует указывать при выполнении кросс-вики запросов по вики-сайтам с помощью CentralAuth; см. задача 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)