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]').

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

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


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

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

Используйте любой язык программирования для отправления 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, и оно имеет свою собственную расширенную документацию. То, что последует, будет просто описанием простого примера.

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

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

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

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



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


 * ЧаВО.
 * Страница о форматах ввода и вывода
 * Страница об ошибках и предупреждениях
 * Какие-либо условия и правила, применимые к вики, к которой вы хотите получить доступ, например, условия использования или политика в отношении торговых марок у вики Фонда Викимедиа. Вы должны выполнять эти условия, когда вы читаете или редактируете вики через 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 в целом:


 * Песочница API, доступная на всех вики Викимедиа, делает несложным интерактивное тестирование различных действий.
 * [//en.wikipedia.org/w/api.php Справка по API] содержит автоматически генерируемые описания всех действий и параметров.
 * Включитесь в информацию Википедии, используя PHP и API MediaWiki (Статья IBM developerWorks, 17 мая 2011 г.)
 * Зайдите в Википедию, используя Java и API MediaWiki (6 апреля 2012 г.)
 * Список рассылки для уведомлений и вопросов: Список рассылки API
 * Низкотрафиковый список рассылки исключительно для объявлений (все сообщения в этом списке также отправляются на mediawiki-api): mediawiki-api-announce
 * Просмотреть и сообщить об ошибках в API на проекте Phabricator MediaWiki-API (Когда сообщаете о новой ошибке, не забывайте добавлять MediaWiki-API в поле Проекты (Projects))
 * — Текущая схема баз данных MediaWiki
 * — Текущая схема баз данных MediaWiki

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

 * Обсуждение API за 2006 год