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 l’interface d'extension, qui autorise les développeurs PHP à ajouter de nouvelles fonctionnalités à une installation MediaWiki.

L'API a web de MediaWiki peut être utilisée pour surveiller une installation MediaWiki, ou créer un robot pour en maintenir une automatiquement. Elle 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 modifications 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:

https://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'aide pour l'API générée automatiquement documente toutes les actions disponibles sur un wiki. Dans ce cas, nous utilisons l'action « query » 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.

Vous pouvez vous enquérir de nombreux types d'informations, ou propiétés, à propos d'une page. Ce paramètre indique à l'API du service web que nous voulons des informations à propos d'une révision particulière de la 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; 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 :


 * la FAQ ;
 * la page sur les formats d'entrée et de sortie ;
 * la page sur les erreurs et avertissements.
 * toute charte qui s'applique au wiki auquel vous souhaitez accéder, comme (pour les wikis de la fondation Wikimedia) nos conditions d'utilisation. Ces conditions vous sont applicables lorsque vous accédez au wiki ou l'éditez à travers l'API du service web, de la même façon que lorsque vous utilisez votre navigateur internet.

Après ceci, ce que vous devez lire dépend de ce que vous souhaitez faire. Le menu de droite propose des liens vers de la documentation détaillée, spécifique pour chaque tâche, ou vous trouverez ci-dessous des indications plus générales.

Identification de votre client
Lorsque vous faites des requêtes HTTP à l'API du service web MediaWiki, assurez-vous d'indiquer un en-tête  qui identifie correctement votre client. N'utilisez pas la valeur par défaut  fournie par la bibliothèque cliente, mais créez un en-tête personnalisé qui identifie votre script ou votre service et fournit des moyens de vous contacter (par exemple, une adresse électronique).

Voici à quoi pourrait ressembler une chaîne User-Agent : MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

Sur les wikis Wikimedia, si vous ne fournissez pas d'en-tête, ou si vous en fournissez un vide ou un générique, vous requêtes échoueront avec une erreur HTTP 403 (cf. User-Agent policy). Les autres installations de MediaWiki peuvent avoir des politiques semblables.

Si vous appelez l'API à partir d'un JavaScript dans un navigateur, vous ne pourrez pas modifier l'en-tête  : le navigateur utilisera le sien. Pour contourner cela, utilisez l'en-tête  :

En PHP, vous pouvez identifier votre client avec un code tel que celui-ci :

Ou, si vous utilisez cURL :

Connexion
Votre client aura probablement besoin de se connecter à MediaWiki, peut-être avec son propre compte utilisateur. Voir la page de manuel de connexion pour de plus amples informations.

Bonnes pratiques de l'API
Veuillez également lire API:Etiquette

Si vos requêtes récupèrent des des données qui peuvent être mises en cache, vous devriez faire ce qu'il faut pour les mettre en cache afin de ne pas avoir à demander plusieurs fois les mêmes données. Vous pouvez trouver de plus amples informations sur la limitation des taux de transfert, les accès concurrents et les bonnes pratiques générales de l'API à la page API:Etiquette. Certains clients peuvent être capable de mettre eux-mêmes les données en caches, mais, pour d'autres (en particulier les clients JavaScript), ce n'est pas possible.

Conformément aux spécifications HTTP, les requêtes POST ne peuvent être cachées. Aussi, lorsque vous accédez à des données depuis l'API du service web, vous devriez utiliser des requêtes GET et non POST.

Veuillez également noter qu'une requête ne peut pas être servie à partir du cache à moins que l'URL ne soit exactement la même. Si vous faites une requête  et mettez le résultat en cache, alors une requête   ne passera pas par le cache — même si MediaWiki renvoie les mêmes données !

Vous devriez faire attention à la normalisation des URL que vous envoyez au service web MediaWiki afin que des saisies d'utilisateurs légèrement différentes ne vous fassent pas perdre de temps en requêtes HTTP inutiles. Vous pouvez normaliser une liste de titres de pages en supprimant les doublons et en triant les titres dans l'ordre alphabétique. Des techniques semblables fonctionnent pour d'autres types de données.

Liens utiles
La barre de menu sur la droite de cette page fournit des liens vers une documentation plus détaillée et plus spécifique. Voici quelques liens en relation avec toute l'API :
 * le bac à sable de l'API disponible sur tous les wikis Wikimedia permet d'essayer facilement différents actions de manière interactive ;
 * la [//en.wikipedia.org/w/api.php référence sur API] contient les descriptions de toutes les actions et de tous les paramètres, elles sont générées automatiquement ;
 * Hook into Wikipedia information using PHP and the MediaWiki API, Accéder à Wikipedia avec PHP et l'API MadiaWiki, article en anglais de IBM developerWorks, 17 mai 2011 ;
 * Hook into Wikipedia using Java and the MediaWiki API, Accéder à Wikipedia avec Java et l'API MediaWiki, article en anglais, 6 avril 2012 ;
 * le didacticiel de l'API vous guide par des exercices pratiques et contient une vidéo d'apprentissage ;
 * la liste de diffusion, en anglais, pour les informations et les questions : API mailing list ;
 * la liste de diffusion à faible trafic réservée aux annonces (tout envoi sur cette liste est également posté sur mediawiki-api) : mediawiki-api-announce
 * voir les bogues et en reporter dans le projet Phabricator MediaWiki-API (n'oubliez pas d'ajouter MediaWiki-API au Projects lorsque vous rapportez de nouveaux bogues) ;
 * — le schéma actuel de la base de données MediaWiki ;
 * — le schéma actuel de la base de données MediaWiki ;

Archives

 * discussions de 2006 sur l'API, en anglais.