API:Page principale
![]() |
Cette page fait partie de la documentation de l'API MediaWiki. |
MediaWiki action API
- Guide de démarrage rapide
- FAQ
- Formats
- Signaler les erreurs
- Restrictions d'usage
- Cross-site requests
- Authentification
- Requêtes
- Searching (by title, content, coordinates...)
- Analyse du wikitext et expansion des modèles
- Purger les pages de cache
- Parameter information
- Changer le contenu du wiki
- Créer et modifier des pages
- Déplacer des pages
- Merge pages
- Rollback
- Supprimer des pages
- Restaurer des versions effacées
- (Dé)protéger des pages
- (Dé)bloquer des utilisateurs
- (dé)suivre des pages
- Marquer des versions des pages suivies comme vérifiées
- Envoyer un courriel
- Surveiller les modifications
- Importer des pages
- Modifier l'appartenance à un groupe d'un utilisateur
- Téléverser des fichiers
- Options utilisateur
- Jetons
- Langue de la page
- More...
- Watchlist feed
- Wikidata
- Extensions
- Utiliser l'API dans MediaWiki et ses extensions
- Divers
- Mise en œuvre
- Client code
- Supposer vrai
- Ceci est une présentation de l'API "action". Voir la barre de menu sur la droite pour des sous-catégories plus détaillées et d'autres APIs.
L'action API Médiawiki 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, via une URL, se trouvant généralement à l’adresse api.php
.
Les clients demandent des "actions" particulières en spécifiant un paramètre action
, souvent action=query
pour récupérer de l'information.
Elle était connue sous le nom d'API MediaWiki, mais MediaWiki offre maintenant d'autres APIs web comme RESTBase et le service de requêtes Wikidata.
Contents
Introduction
L'API action 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 Toolforge).
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'Help:Export pour plus d'informations.
- l'interface web standard (que vous êtes probablement en train d'utiliser pour lire cette page). Lisez Manuel:Paramètres de index.php 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:
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 jsonfm
retournera un affichage HTML mis en forme élégamment, utile pour le débogage.
Voici l'URL jsonfm en tant que lien cliquable "plus facile à lire".
Prenons l'URL à part pour montrer comment cela fonctionne.
L'URL principale
https://en.wikipedia.org/w/api.php
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 https://en.wikipedia.org/wiki/
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 :
https://www.mediawiki.org/w/api.php # API MediaWiki
https://en.wikipedia.org/w/api.php # API Wikipédia Anglaise
https://nl.wikipedia.org/w/api.php # API Wikipédia Néerlandaise
https://commons.wikimedia.org/w/api.php # API Wikimedia Commons
Version de MediaWiki : | ≥ 1.17 |
Depuis la révision r75621, nous avons un système de découverte RSD pour l'URL de base : cherchez le link rel="EditURI"
dans le code source HTML de n'importe quelle page et extrayez l'URL api.php
; le lien contient des informations additionnelles.
Pour information, sur le wiki il s'agit de :
<link rel="EditURI" type="application/rsd+xml" href="//www.mediawiki.org/w/api.php?action=rsd" />
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 w/api.php
).
Maintenant, passons aux paramètres contenus dans la chaîne de requête de l'URL.
format
format=json
Ceci demande à l'API du service web de Wikimedia de retourner les données en format JSON.
Vous pourriez aussi vouloir essayer le format format=jsonfm
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 (phab:T95715), il est donc recommandé de ne pas les utiliser.
action
action=query
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
titles=Main%20Page
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 : titles=PageA|PageB|PageC
.
Voyez la documentation de query pour plus de détails.
prop=revisions
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 — la page principale de Wikipédia comme elle est actuellement.
rvprop=content
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é rvprop=content|user
à 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 query
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 rvprop
, 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, où 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 User-Agent
qui identifie correctement votre client. N'utilisez pas la valeur par défaut User-Agent
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 User-Agent
, ou si vous en fournissez un vide ou un générique, vous requêtes échoueront avec une erreur HTTP 403 (cf. m: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 User-Agent
: le navigateur utilisera le sien. Pour contourner cela, utilisez l'en-tête Api-User-Agent
:
// Using XMLHttpRequest
xhr.setRequestHeader( 'Api-User-Agent', 'Example/1.0' );
// Using jQuery
$.ajax( {
url: remoteUrlWithOrigin,
data: queryData,
dataType: 'json',
type: 'POST',
headers: { 'Api-User-Agent': 'Example/1.0' },
success: function(data) {
// do something with data
}
} );
// Using mw.Api, specify it when creating the mw.Api object
var api = new mw.Api( {
ajax: {
headers: { 'Api-User-Agent': 'Example/1.0' }
}
} );
api.get( {...} ).done(function(data) {
// do something with data
});
// Using fetch
fetch( remoteUrlWithOrigin, {
method: 'POST',
headers: new Headers( {
'Api-User-Agent': 'Example/1.0'
} )
// Other init settings such as 'credentials'
} ).then( function ( response ) {
if ( response.ok ) {
return response.json();
}
throw new Error( 'Network response was not ok: ' + response.statusText );
} ).then( function ( data ) {
// do something with data
});
En PHP, vous pouvez identifier votre client avec un code tel que celui-ci :
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');
Ou, si vous utilisez cURL :
curl_setopt($curl, CURLOPT_USERAGENT, 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');
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 capables 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 api.php?....titles=Foo|Bar|Hello
et mettez le résultat en cache, alors une requête api.php?....titles=Hello|Bar|Hello|Foo
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 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 MediaWiki, 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 ;
- 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) ;
- naviguer dans le code source de l'API ;
- Manuel:Schéma de base de donnée — le schéma actuel de la base de données MediaWiki ;
- naviguer dans la schéma actuel de la base de données dans git.
Archives
- discussions de 2006 sur l'API, en anglais.