API:Main page/ru


 * Это вводный обзор. Разделы с более подробной информацией ищите в меню справа.

Веб-API MediaWiki — это веб-служба, предоставляющая удобный доступ к функциям, данным и метаданным вики по HTTP.

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

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

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

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


 * Страница Special:Export, которая предоставляет массовый экспорт контента вики в XML. Для подробностей смотрите статью, описывающую экспорт на 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, не забудьте прочитать следующие документы:


 * The FAQ.
 * The page about input and output formats
 * The page about errors and warnings
 * Any policies that apply to the wiki you want to access, such as (for Wikimedia Foundation wikis) our terms of use. These terms apply to you when you access or edit using the web service API, just as they do when you use your web browser.

Beyond that point, what you need to read depends on what you want to do. The right-hand menu links to detailed, task-specific documentation, and some more general guidelines are given below.

Identifying your client
When you make HTTP requests to the MediaWiki web service API, be sure to specify a  header that properly identifies your client. Don't use the default  provided by your client library, but make up a custom header that identifies your script or service and provides some type of means of contacting you (e.g., an e-mail address).

An example User-Agent string might look like: MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

On Wikimedia wikis, if you don't supply a  header, or you supply an empty or generic one, your request will fail with an HTTP 403 error (cf. User-Agent policy). Other MediaWiki installations may have similar policies.

If you are calling the API from browser-based JavaScript, you won't be able to influence the  header: the browser will use its own. To work around this, use the  header:

In PHP, you can identify your user-agent with code such as this:

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

Вход
Your client will probably need to log in to MediaWiki, possibly via its own user account. See the login manual page for details.

Этикет использования API
Please also read: API:Etiquette

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. More information about rate-limiting, concurrency, and general API etiquette can be found at API:Etiquette. 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.

Полезные ссылки
The menu bar on the right side of this page links to more detailed, task-specific documentation. Here are some links having to do with the API as a whole:
 * 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