API:Tutoriel
| Cette page fait partie de la documentation de l'API MediaWiki Action. |
Dans ce tutoriel, vous découvrirez ce qu'est l' API Action de MediaWiki, comment l'utiliser, le format des requêtes, une requête simple et des exemples de projets qui utilisent l'API Action.
Aperçu de l'API Action de MediaWiki
L' API Action de MediaWiki est un service web utilisant REST et qui permet aux utilisateurs de réaliser certaines actions sur les wikis telles que la création de page, l'authentification, l'analyse syntaxique, la recherche, etc. API:Page d'accueil est un bon point d'entrée pour comprendre l'API.
Votre programme envoie des requêtes à l'API pour avoir accès aux fonctionnalités du wiki. Par exemple se connecter à un wiki, créer ou modifier une page, rechercher un titre, chercher une texte dans le contenu, ou analyser un contenu. L'API Action est disponible pour les développeurs tiers, les développeurs d'extensions Wikimedia, et les administrateurs de site.
Dans la barre latérale droite de cette page il existe plusieurs fonctions réalisées par l'API et groupées par catégorie. Avant d'envoyer les requêtes à un serveur wiki, lisez d'abord les pages de présentation telles que les formats des données, les erreurs et les avertissements, et la FAQ de l'API Action.
Comment utiliser l'API Action de MediaWiki
Vous pouvez demander des données sur le serveur à partir d'un client avec le protocole HTTP et obtenir en retour la réponse dans un format standard (typiquement en JSON). Une requête est constituée d'un point d'accès et d'une série de paramètres. Vous pouvez utiliser deux types de requêtes : GET et POST. Dans une requête GET, un paramètre contient la chaîne de caractères de la requête dans l'URL. Dans les requêtes POST, mettez les paramètres au format JSON.
Format de la requête
Tous les Wikis Wikimedia possèdent des points d'accès de ce format http://example.org/w/api.php.
Pour opérer sur le site principal de MediaWiki ou celui de la Wikipedia anglophone, utilisez le point d'accès qui lui correspond.
Par exemple, la Wikipedia anglophone se trouve sur https://en.wikipedia.org/w/api.php.
Pour tester de nouveaux comptes ou pour tester les modifications de pages, utilisez le point d'accès du wiki de test https://test.wikipedia.org/w/api.php.
Dans l'URL de la chaîne de la requête, ajoutez le paramètre action.
Il indique à l'API l'action à réaliser.
L'action la plus populaire est query (l'URL va contenir action=query), ce qui permet de rechercher des données dans un wiki.
Après le paramètre action, ajoutez un autre paramètre pour indiquer quel type de module de recherche parmi les trois vous voulez exécuter :
prop- obtenir les propriétés des pageslist- obtenir la liste des pages qui vérifient un certain critèremeta- obtenir les méta informations concernant le wiki et les utilisateurs
Enfin, ajoutez le paramètre format, qui indique à l'API dans quel format les résultats doivent être fournis.
Le format recommandé est JSON.
Dans le passé, l'API prenait en charge d'autres formats de sortie, mais il est recommandé de ne plus les utiliser.
Une requête simple
Prenons un exemple d'une requête simple pour comprendre à quoi ressemble une requête GET typique ainsi que sa réponse dans le contexte de l'API Action.
Essayons de chercher un titre dans un wiki. Nous utiliserons le module search documenté sur API:Search/fr.
Requête GET
Pour rechercher des titres de pages ou du contenu qui avec Craig Noone, l'URL de la requête HTTP GET sera :
Explication de chaque partie de l'URL :
http://en.wikipedia.org/w/api.phpest le point d'accès principal. Dans ce cas il s'agit de la Wikipedia anglophone.action=querysignifie rechercher les données dans le wiki.list=searchsignifie obtenir la liste des pages qui vérifient un critère.srsearch=Craig%20Nooneindique le titre la page ou le contenu à rechercher. Le%20représente un caractère espace dans une URL.format=jsonindique la sortie en JSON, qui est le format de sortie recommandé.
Réponse
La réponse est un document au format JSON avec une liste de titres des pages qui correspondent à Craig Noone :
{
"batchcomplete": "",
"continue": {
"sroffset": 10,
"continue": "-||"
},
"query": {
"searchinfo": {
"totalhits": 210
},
"search": [
{
"ns": 0,
"title": "Craig Noone",
"pageid": 18846922,
"size": 22548,
"wordcount": 1771,
"snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
"timestamp": "2018-11-02T22:25:45Z"
},
{
"ns": 0,
"title": "Noone",
"pageid": 32906333,
"size": 553,
"wordcount": 64,
"snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to: <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
"timestamp": "2015-08-16T05:16:17Z"
}
...
]
}
}
Exemples de projets qui utilisent l'API Action
Exemples de projets de Wikimedia qui utilisent l'API Action :
- Appli Wikipedia iOS, dont l'une des fonctionnalités est de rechercher des pages wiki en rapport avec le voisinage de votre emplacement.
- Robots qui opèrent sur un wiki. Pywikibot est un environnement pour les robots, écrit en Python, et qui s'interface avec l'API MediaWiki utilisée par beaucoup de développeurs de robots.
- L'utilisation de l'API permet de visualiser les données obtenues d'un wiki. Comme cette visualisation soignée montrant les éditions en temps réel les modifications faites sur Wikipedia.
Notes supplémentaires
- Plusieurs sites utilisent MediaWiki. Il est possible qu'il exécutent des versions différentes de MediaWiki et donc de l'API. Certains paramètres de module pris en charge dans une version peuvent être obsolètes ou supprimés dans une autre. Vous pouvez le savoir en regardant la documentation de chaque module via le module d'aide de l'API.
- Si vous souhaitez réaliser un grand nombre d'appels à l'API, et peut être exécuter des robots très occupés et actifs, parlez-en d'abord aux administrateurs du wiki, afin qu'ils ne vous bloquent pas. Voir la liste des Administrateurs des projets Wikimedia. Lire les autres informations sur ce sujet sur API:Etiquette.
- Toutes les actions de modification des données comme la journalisation, la modification ou le renommage d'une page ainsi que le suivi ou les modifications du patrouillage nécessitent des jetons. Il vous faudra obtenir des jetons via API:Tokens pour pouvoir continuer.
Ressources
- Utilisez Special:APISandbox pour essayer l'API Action.
Vous pouvez tester en essayant les actions prises en charge, en spécifiant la valeur des paramètres, et en envoyant les requêtes à l'API pour voir les résultats sur la même page.
- Vidages Wikimedia pour les analyser localement.
- Lisez les tutoriels : Introduction aux APIs et REST c'est quoi ? — une explication simple pour les débutants.
- API help de MediaWiki fournit la documentation auto générée de l'API de tous les modules pris en charge.
- API:Page d'accueil fournit un aperçu de l'API Action.
- Introduction à l'API MediaWiki par User:Roan Kattouw (WMF) au Hackathon de San Francisco, 2012. Ce tutoriel suit la vidéo.
- GitHub: Démonstrations de l'API MediaWiki