API:Main page/fr


 * Ceci est une présentation d'introduction. Voir la barre de menu sur la droite pour des sous-catégories plus détaillées.

L'API web MediaWiki est un service web qui fournit un accès facile aux fonctionnalités du wiki, de ses données, et de ses méta-données via HTTP.

Introduction
Si vous cherchez plutôt une API interne ou une API PHP, voir le extension interface, qui autorise les développeurs PHP à ajouter de nouvelles fonctionnalités à une installation MediaWiki.

La web API de MediaWiki peut être utilisée pour controller une installation MediaWiki, ou créer un robot pour en maintenir une automatiquement. Il fournit un accès direct et de haut niveau aux données contenues dans les bases de données MediaWiki. Des programmes clients peuvent se connecter à un wiki, obtenir les données, et poster automatiquement les changements en envoyant des requêtes HTTP au service web. Les clients supportés incluent les robots, les clients web JavaScript légers comme les popups de navigation et LiveRC, les applications utilisateurs finaux comme Vandal Fighter, et les autres sites web (utilitaires [//tools.wmflabs.org Tool Labs]).

Dans les nouvelles installations MediaWiki, le service web est activé par défaut, mais un administrateur peut le désactiver.

MediaWiki a deux autres interfaces tournées vers l'extérieur:


 * La page Special:Export, qui fournit un export brut du contenu du wiki en XML. Lisez l'article d'aide à l'export sur meta.wikimedia.org pour plus d'informations.
 * L'interface web standard (que vous êtes probablement en train d'utiliser pour lire cette page). Lisez pour plus d'informations sur l'utilisation de l'interface web.

Un exemple simple
Cette URL demande au service web Anglais de Wikipédia de vous envoyer le contenu de la page principale:

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

Utilisez n'importe quel langage de programmation pour envoyer une requête HTTP GET pour cette URL (ou consultez simplement ce lien dans votre navigateur), et vous obtiendrez un document JSON qui contient le code source actuel de la page appelée "Main Page". Changer le format en  retournera un affichage HTML mis en forme élégamment, utile pour le débogage.

Prenons l'URL à part pour montrer comment cela fonctionne.

L'URL principale
Ceci est l'URL principale. Cela peut être comparé à la page principale de l'API du service web MediaWiki. Cette URL est l'URL de base pour l'API Wikipédia Anglaise, tout comme  est l'URL de base pour ce site web.

Si vous écrivez un programme pour utiliser le Wikipédia Anglais, chaque URL que vous utiliserez commencera par cette URL de base. Si vous utilisez une installation MediaWiki différente, vous aurez besoin de trouver son URL de base et de l'utiliser à la place. Tous les wikis Wikimedia ont des URL de base qui suivent ce schéma :

Depuis la révision, nous avons un système de découverte RSD pour l'URL de base : cherchez le  dans le code source HTML de n'importe quelle page et extrayez l'URL  ; le lien contient des informations additionnelles. Pour information, sur le wiki il s'agit de :

Autrement, il n'y a aucune manière sûre de trouver l'URL de base d'un wiki. Si vous êtes chanceux, soit le chemin complet vers index.php ne sera pas caché à travers des règles de redirection étranges, dans ce cas vous n'aurez qu'à récupérer le lien "voir le code source" (ou "historique") et de remplacer index.php par api.php, soit vous pourrez utiliser le script path par défaut (comme ).

Maintenant, passons aux paramètres contenus dans la chaîne de requête de l'URL.

format
Ceci demande à l'API du service web de Wikimedia de retourner les données en format JSON. Vous pourriez aussi vouloir essayer le format  pour récupérer une version HTML du résultat, utile pour le débogage. L'API supporte d'autres formats de sortie comme XML et PHP natif, mais il est prévu de supprimer les formats les moins populaires (T95715), il est donc recommandé de ne pas les utiliser.

action
L'API du service web de MediaWiki implémente de nombreuses actions et les extensions en implémentent encore plus; L'[//en.wikipedia.org/w/api.php aide pour l'API] générée automatiquement documente toutes les actions disponibles sur un wiki. Dans ce cas, nous utilisons l'action "qyery" pour récupérer des informations. L'action "query" est une des actions les plus importantes de l'API, et elle a une documentation à part entière. Ce qui suit est simplement une explication d'un seul exemple.

Paramètres spécifiques à action
Le reste de l'URL d'exemple contient des paramètres utilisés par l'action "query". Ici, nous demandons à l'API du service web des informations à propos de la page du Wiki appelée "Main Page". (Le %20 vient de l'encodage de l'espace en percent-encoding) Si vous avez besoin de travailler avec plusieurs pages, vous pouvez les demander dans une seule et même requête pour optimiser les ressources serveur et réseau:. Voyez la documentation de query pour plus de détails.

You can request many kinds of information, or properties, about a page. This parameter tells the web service API that we want information about a particular revision of the page. Puisque nous ne fournissons aucune information sur la révision que nous cherchons, l'API va nous donner la dernière révision &mdash; la page principale de Wikipédia comme elle est actuellement.

Enfin, ce paramètre indique à l'API du service web que nous voulons le contenu de la dernière révision de la page. Si nous avions donné  à la place, nous aurions obtenu la dernière révision et le nom de l'utilisateur qui a fait la modification la plus récente.

Encore une fois, ceci est juste un exemple. Les requêtes  sont expliquées plus en profondeur ici, et la référence de l'API liste toutes les actions possibles et toutes les valeurs possibles pour , et tout les autres arguments.



Pour commencer
Avant d'utiliser l'API du service web de MediaWiki, lisez ces documents :
 * 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