API:Main page/ru


 * Это обзор действий, выполняемых с помощью API. Разделы с более подробной информацией и другие API ищите в меню справа.

API действий MediaWiki (MediaWiki action API) — это веб-служба, предоставляющая удобный доступ к функциям, данным и метаданным вики по HTTP, с помощью URL-адресов вида. Клиенты запрашивают различные «действия», указывая параметр, чаще всего  , чтобы получить информацию. Он был известен как  единственный  API движка MediaWiki, но теперь существуют другие сетевые API, соединяющиеся с MediaWiki, такие как RESTBase и служба запросов к Викиданным.

Введение
Если вы ищете «внутренний API» или «PHP API», смотрите интерфейс для расширений, позволяющий PHP разработчикам добавлять в MediaWiki новый функционал.

Веб-API MediaWiki можно использовать для мониторинга проекта на базе MediaWiki, или для создания бота в целях его обслуживания. Он обеспечивает прямой высокоуровневый доступ к данным, содержащимся в базах данных MediaWiki. Клиентские программы могут автоматически логиниться в вики, получать данные и вносить изменения, совершая HTTP запросы к веб-службе. Поддерживаемые клиенты включают ботов, тонкие веб-клиенты на JavaScript, такие как Навигационные окошки и LiveRC, пользовательские приложения, такие как Vandal Fighter и другие веб-сайты (инструменты [//tools.wmflabs.org Tool Labs]').

Special:MyLanguage/API:Restricting API usage#Disabling the entire APISpecial:MyLanguage/API:Restricting API usage#Disabling the entire APIВ новых установках MediaWiki веб-служба разрешена по-умолчанию, но администратор может её заблокировать.

MediaWiki имеет ещё два внешних интерфейса:


 * Страница Special:Export, которая предоставляет массовый экспорт контента вики в XML.Special:Export Для подробностей смотрите статью, описывающую экспорт на meta.wikimedia.org.
 * Стандартный веб-интерфейс (которым вы с большой долей вероятности пользуетесь сейчас, читая эту страницу). Чтобы узнать о том, как пользоваться веб-интерфейсом, прочтите.

Пример
Этот URL велит веб-службе API английской Википедии отправить вам содержимое главной страницы:

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

Используйте любой язык программирования для отправления GET-запроса HTML по этому URL (либо просто перейдите по этой ссылке в своём браузере), и вы получите JSON-документ, содержащий вики-разметку для страницы с названием «Main Page». Замена формата на  вернёт удобный для отладки результат, «структурированный» с помощью HTML.

Давайте разберём этот URL по частям, чтобы понять, как это работает.

Конечная точка
Это — «конечная точка» (endpoint). Это место — что-то вроде домашней страницы веб-службы API для MediaWiki. Этот URL — базовый URL для API английской Википедии, также как  — базовый URL для её веб-сайта.

Если вы пишете программу для работы с английской Википедией, любой URL, который вы строите, будет начинаться с этого базового URL. Если вы работаете с другии проектом MediaWiki, вам требуется найти его конечную точку и использовать именно её. Для всех вики-сайтов Викимедиа имеются конечные точки, устроенные по следующему шаблону:

Начиная с, мы поддерживаем RSD-нахождение конечной точки: ищите  в исходном коде HTML любой страницы и получите URL  ; сама же ссылка содержит дополнительную информацию. Например, для этой вики она является:

Не существует иного безопасного пути нахождения конечной точки на какой-либо вики. Если вам повезёт, либо полный путь к index.php не будет скрыт под странными правилами переписывания так, что вам останется только взять ссылку редактирования (или истории) и заменить index.php (и т. д.) с api.php, либо вы сможете использовать путь скрипта по умолчанию (вроде ).

Теперь давайте перейдём к параметрам запроса в URL.

Формат
Этот параметр сообщает веб-службе API Викимедиа, что мы ожидаем данные в формате JSON. Возможно, вы захотите использовать, чтобы получить удобную для отладки HTML-версию результата. API поддерживает и другие форматы вывода, такие как XML и родной PHP, однако менее популярные форматы планируется убрать (T95715), так что вы можете не захотеть использовать их.

Действие
Веб-служба API MediaWiki реализует десятки действий, а её расширения — ещё больше; динамически генерируемая справка API описывает все доступные операции с вики-сайтом. В нашем случае мы использовали действие «query» для получения некоторой информации. Действие «query» является одним из самых нужных в API, и оно имеет extensive documentation of its own. То, что последует, будет просто описанием простого примера.

Параметры действий
Оставшаяся часть нашего URL содержит параметры для действия «query». Здесь мы сообщаем веб-службе API о том, что хотим информацию о викистранице с названием "Main Page". (Загадочное %20 — это URL-кодировка символа пробела). Если вам нужно запросить множество страниц, укажите их все в одном запросе для оптимизации ресурсов сети и сервера:. Для подробностей смотрите документацию по query.

Вы можете запрашивать различные виды информации о странице, в виде т.н. свойств — properties. Этот параметр говорит веб-службе API, что нам нужна информация об определённой версии страницы. Если мы не укажем информацию о ревизии, API даст нам информацию о последней ревизии главной страницы Википедии на текущий момент.

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

Это всего лишь один пример. Подробнее запросы расписаны здесь, а в справке API перечислены все возможные действия, а также все возможные значения для  и многое другое.



С чего начать
Перед тем, как вы начнёте пользоваться веб-службой API MediaWiki, не забудьте прочитать следующие документы:


 * FAQ.
 * Страница о форматах ввода и вывода
 * Страница об ошибках и предупреждениях
 * Какие-либо условия и правила, применимые к вики, к которой вы хотите получить доступ, например, условия использования или политика в отношении торговых марок у вики Фонда Викимедиа. Вы должны выполнять эти условия, когда вы читаете или редактируете вики через API точно так же, как и при использовании веб-браузера.

Помимо этого, то, что вам необходимо прочитать, зависит от того, что вы хотите сделать. Меню справа ссылается на подробную документацию, в которой расписана каждая задача, а более общие принципы работы указаны ниже.

Идентификация клиентского приложения
Когда вы делаете HTTP-запросы к API сетевых служб движка MediaWiki, обязательно укажите заголовок, правильно идентифицирующий ваш клиент. Не используйте значение этого заголовка, предоставляемое вашей клиентской библиотекой по умолчанию. Вместо этого придумайте собственный заголовок, идентифицирующий ваш скрипт или службу и предоставляющий какие-либо способы связаться с вами (например, адрес электронной почты).

Пример строки User-Agent: MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

На вики Викимедиа, если вы не предоставляете заголовок  или предоставляете пустой или неконкретный, ваш запрос будет неудачен, и вы получите ошибку HTTP 403 (обратитесь к User-Agent policy). Другие сайты, на которых установлен MediaWiki, могут использовать подобную политику.

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

В PHP вы можете идентифицировать свою программу-агент, например, кодом, подобным этому:

Или если ты используешь cURL:

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

Этикет использования API
Также следует прочитать: API:Этикет

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

Согласно спецификации протокола HTTP, POST-запросы не могут быть кэшированы. Таким образом, когда вы читаете данные из API сетевых служб, вам следует использовать метод GET, а не POST.

Также обратите внимание, что запрос не может быть обращён к кэшу, если в URL есть хоть какие-то различия. Если вы делаете запрос по адресу, последующий запрос к   не обратится к кэшу, хотя MediaWiki возвращает те же данные!

Вам следует позаботиться о нормализации URL, которые вы посылаете сетевой службе MediaWiki, чтобы незначительно иной ввод пользователя не привёл к потере времени на ненужные HTTP-запросы. Вы можете нормализовать список названий страниц, удалив дубликаты и отсортировав названия в алфавитном порядке. Подобные методики работают для других видов данных.

Полезные ссылки
Меню в правой части этой страницы ссылается на более подробную, специфическую для заданий документацию. Вот некоторые ссылки, относящиеся к API в целом:
 * The API sandbox available on all Wikimedia wikis makes it easy to try out different actions interactively.
 * [//en.wikipedia.org/w/api.php 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)
 * Hook into Wikipedia using Java and the MediaWiki API (6 April 2012)
 * The API tutorial leads you through hands-on exercises and includes a training video.
 * Mailing list for notifications and questions: API mailing list
 * Low-traffic mailing list for announcements only (all posts to this list are posted to mediawiki-api as well): mediawiki-api-announce
 * View and report API bugs in the MediaWiki-API Phabricator project (When reporting new bugs, don't forget to add MediaWiki-API to Projects)
 * — The current MediaWiki database schema
 * — The current MediaWiki database schema

Архивные ссылки

 * 2006 API discussion