API:Main page/ru


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

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

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

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

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

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


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

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

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

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

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

The endpoint
This is the endpoint. Он подобен домашней странице веб-службы API MediaWiki. Этот URL - базовый для API английской Википедии, также как  - базовый URL для её веб-сайта.

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

Since, we have RSD discovery for the endpoint: look for the  in the HTML source of any page and extract the   URL; the actual link contains additional info. For instance, on this wiki it's:

Otherwise, there's no safe way to locate the endpoint on any wiki. If you're lucky, either the full path to index.php will not be hidden under strange rewrite rules so that you'll only have to take the "edit" (or history) link and replace index.php (etc.) with api.php, or you'll be able to use the default script path (like ).

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

format
сообщает веб-службе API Wikimedia, что мы ожидаем данные в формате JSON. Возможно вы захотите попробовать, чтобы получить HTML версию результата, удобную для отладки. API поддерживает и другие форматы вывода, такие как XML и native PHP, однако менее популярные форматы планируется убрать (T95715), so you might not want to use them.

action
Веб-служба API MediaWiki реализует десятки действий, а её расширения - ещё больше; динамически генерируемая документация [//en.wikipedia.org/w/api.php API help] описывает все доступные действия в вики. В нашем случае мы использовали действие "query" для получения некоторой информации. Действие "query" является одним из самых нужных в API, и оно имеет extensive documentation of its own. What follows is just an explanation of a single example.

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

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

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

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



С чего начать
Перед тем, как вы начнёте пользоваться веб-службой 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 (http://example.com/MyCoolTool/; MyCoolTool@example.com) 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:

Or if you use cURL:

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

API etiquette
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.

Useful links
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

Archived links

 * 2006 API discussion