Aide:API

De Wikidébats, l'encyclopédie des débats et des arguments « pour » et « contre »
Aller à la navigation Aller à la recherche

Module principal[modifier | modifier le wikicode]

  • Documentation
  • FAQ
  • Liste de diffusion
  • Annonces de l’API
  • Suivi des anomalies et demandes d’amélioration

État : l’API de MediaWiki est une interface stable et mature qui est supportée et améliorée de façon active. Bien que nous essayions de l’éviter, nous pouvons avoir parfois besoin de faire des modifications impactantes ; inscrivez-vous à la liste de diffusion mediawiki-api-announce pour être informé des mises à jour.

Requêtes erronées : si des requêtes erronées sont envoyées à l’API, un entête HTTP sera renvoyé avec la clé « MediaWiki-API-Error ». La valeur de cet entête et le code d’erreur renvoyé prendront la même valeur. Pour plus d’information, voyez API:Erreurs et avertissments.

Test : pour faciliter le test des requêtes à l’API, utilisez le bac à sable de l’API.

Paramètres :

action
Quelle action effectuer.
antispoof
Contrôler un nom d’utilisateur d’après la normalisation de AntiSpoof.
ask
Module d’API pour interroger Semantic MediaWiki avec le langage de requête.
askargs
Module d’API pour interroger Semantic MediaWiki avec le langage de requête comportant une liste de conditions, d’affichages et de paramètres.
block
Bloquer un utilisateur.
changeauthenticationdata
Modifier les données d’authentification pour l’utilisateur actuel.
changecontentmodel
Modifier le modèle de contenu d’une page
checktoken
Vérifier la validité d’un jeton de action=query&meta=tokens.
cirrus-config-dump
Dump de la configuration de CirrusSearch.
cirrus-mapping-dump
Vidage de la table de correspondance de CirrusSearch pour ce wiki.
cirrus-profiles-dump
Vidage des profils CirrusSearch de ce wiki.
cirrus-settings-dump
Vidage des paramètres de CirrusSearch pour ce wiki.
clearhasmsg
Efface le drapeau hasmsg pour l’utilisateur actuel.
clientlogin
Se connecter au wiki en utilisant la procédure interactive.
compare
Obtenir la différence entre deux pages.
createaccount
Créer un nouveau compte utilisateur.
delete
Supprimer une page.
echomarkread
Marquer les notifications comme lues pour l’utilisateur actuel.
echomarkseen
Marquer les notifications comme vues pour l’utilisateur courant.
echomute
Faire taire ou non les notifications de certains utilisateurs ou pages.
edit
Créer et modifier les pages.
editmassmessagelist
Modifier une liste de diffusion de messages de masse.
emailuser
Envoyer un courriel à un utilisateur.
embedvideo
Get generated video embed code for given parameters.
expandtemplates
Réalise l’expansion des modèles en wikitexte.
ext.srf.slideshow.show
feedcontributions
Renvoie le fil des contributions d’un utilisateur.
feedrecentchanges
Renvoie un fil de modifications récentes.
feedwatchlist
Renvoie un flux de liste de suivi.
filerevert
Rétablir un fichier dans une ancienne version.
flow
Permet d’effectuer des actions sur les pages de Discussions Structurées.
flow-parsoid-utils
Conversion de texte entre du source wiki et du HTML.
flowthank
Envoyer une notification publique de remerciement pour un commentaire Flow.
help
Afficher l’aide pour les modules spécifiés.
imagerotate
Faire pivoter une ou plusieurs images.
import
Importer une page depuis un autre wiki, ou depuis un fichier XML.
jsonschema
Récupérer une page schéma JSON.
linkaccount
Lier un compte d’un fournisseur tiers à l’utilisateur actuel.
login
Se connecter et récupérer les témoins (cookies) d’authentification.
logout
Se déconnecter et effacer les données de session.
managetags
Effectuer des tâches de gestion relatives aux balises de modification.
massmessage
Envoyer un message à une liste de pages.
mergehistory
Fusionner les historiques des pages.
move
Déplacer une page.
opensearch
Rechercher dans le wiki en utilisant le protocole OpenSearch.
options
Modifier les préférences de l'utilisateur courant.
paraminfo
Obtenir des informations sur les modules de l’API.
parse
Analyse le contenu et renvoie le résultat de l’analyseur.
patrol
Patrouiller une page ou une révision.
pfautocomplete
Complétion automatique utilisée par l’extension Page Forms.
pfautoedit
Créer ou modifier une page en utilisant un formulaire défini par l’extension Page Forms.
protect
Modifier le niveau de protection d’une page.
purge
Vider le cache des titres fournis.
query
Extraire des données de MediaWiki et à propos de celui-ci.
removeauthenticationdata
Supprimer les données d’authentification pour l’utilisateur actuel.
resetpassword
Envoyer un courriel de réinitialisation du mot de passe à un utilisateur.
revisiondelete
Supprimer et rétablir des révisions.
rollback
Annuler les dernières modifications de la page.
rsd
Exporter un schéma RSD (Découverte Très Simple).
setnotificationtimestamp
Mettre à jour l’horodatage de notification pour les pages suivies.
setpagelanguage
Modifier la langue d’une page.
smwbrowse
Module API pour supporter l'analyse des activités pour différents types d'entités de Semantic MediaWiki.
smwinfo
Module d'API pour récupérer les informations concernant les statistiques de Semantic MediaWiki ainsi que d'autres informations meta.
smwtask
Module d’API pour exécuter les tâches relatives à Semantic MediaWiki (pour un usage interne uniquement, pas pour un usage public).
spamblacklist
Valider une ou plusieurs URL selon la liste noire de pourriels.
streamconfigs
Expose la configuration du flux d’événements
tag
Ajouter ou enlever des balises de modification aux révisions ou aux entrées de journal individuelles.
templatedata
Récupérer les données stockées par l’extension TemplateData.
thank
Envoyer une notification de remerciement à un éditeur.
titleblacklist
Valider un titre de page, un nom de fichier ou un nom d’utilisateur d’après TitleBlacklist.
unblock
Débloquer un utilisateur.
undelete
Restaurer les versions d’une page supprimée.
unlinkaccount
Supprimer un compte tiers lié de l’utilisateur actuel.
upload
Téléverser un fichier, ou obtenir l’état des téléversements en cours.
userrights
Modifier l’appartenance d’un utilisateur à un groupe.
validatepassword
Valider un mot de passe conformément aux règles concernant les mots de passe du wiki.
veforall-parsoid-utils
Convertir dans les deux sens, de Wikitext en HTML
watch
Ajouter ou supprimer des pages de la liste de suivi de l’utilisateur actuel.
webapp-manifest
Retourne un manifest webapp.
browsebyproperty
Obsolète. Module d’API pour récupérer les informations concernant une propriété ou une liste de propriétés.
browsebysubject
Obsolète. Module d’API pour récupérer les informations concernant un sujet.
mobileview
Obsolète. Renvoie les données nécessaires pour les affichages mobile.
tokens
Obsolète. Obtenir des jetons pour des actions de modification des données.
categorytree
Interne. Module interne pour l’extension CategoryTree.
cspreport
Interne. Utilisé par les navigateurs pour signaler les violations de la politique de confidentialité du contenu. Ce module ne devrait jamais être utilisé, sauf quand il est utilisé automatiquement par un navigateur web compatible avec CSP.
scribunto-console
Interne. Module interne gérant les requêtes XHR à partir de la console Scribunto.
stashedit
Interne. Préparer des modifications dans le cache partagé.
visualeditor
Interne. Renvoie une page HTML5 du service Parsoid.
visualeditoredit
Interne. Enregistrer une page HTML5 dans Médiawiki (convertie en wikitexte via le service Parsoid).
Une des valeurs suivantes : antispoof, ask, askargs, block, changeauthenticationdata, changecontentmodel, checktoken, cirrus-config-dump, cirrus-mapping-dump, cirrus-profiles-dump, cirrus-settings-dump, clearhasmsg, clientlogin, compare, createaccount, delete, echomarkread, echomarkseen, echomute, edit, editmassmessagelist, emailuser, embedvideo, expandtemplates, ext.srf.slideshow.show, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, flow-parsoid-utils, flow, flowthank, help, imagerotate, import, jsonschema, linkaccount, login, logout, managetags, massmessage, mergehistory, move, opensearch, options, paraminfo, parse, patrol, pfautocomplete, pfautoedit, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setnotificationtimestamp, setpagelanguage, smwbrowse, smwinfo, smwtask, spamblacklist, streamconfigs, tag, templatedata, thank, titleblacklist, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, veforall-parsoid-utils, watch, webapp-manifest, browsebyproperty, browsebysubject, mobileview, tokens, categorytree, cspreport, scribunto-console, stashedit, visualeditor, visualeditoredit
Par défaut : help
format
Le format de sortie.
json
Sortir les données au format JSON.
jsonfm
Extraire les données au format JSON (HTML mis en forme améliorée pour l’impression).
none
Ne rien extraire.
php
Extraire les données au format sérialisé de PHP.
phpfm
Extraire les données au format sérialisé de PHP (mise en forme HTML améliorée pour l'impression).
rawfm
Extraire les données, y compris les éléments de débogage, au format JSON (mise en forme HTML améliorée pour l'impression).
xml
Extraire les données au format XML.
xmlfm
Extraire les données au format XML (affiché proprement en HTML).
Une des valeurs suivantes : json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm
Par défaut : jsonfm
maxlag
La latence maximale peut être utilisée quand MediaWiki est installé sur une grappe de réplication de bases de données. Pour éviter des actions provoquant un supplément de latence de réplication de site, ce paramètre peut faire attendre le client jusqu’à ce que la latence de réplication soit inférieure à une valeur spécifiée. En cas de latence excessive, le code d’erreur maxlag est renvoyé avec un message tel que Attente de $host : $lag secondes de délai. Voyez Manuel : paramètre Maxlag pour plus d’informations.
Type: entier
smaxage
Fixer l’entête HTTP de contrôle de cache s-maxage à ce nombre de secondes. Les erreurs ne sont jamais mises en cache.
Type: entier
Par défaut : 0
maxage
Fixer l’entête HTTP de contrôle de cache max-age au nombre indiqué de secondes. Les erreurs ne sont jamais mises en cache.
Type: entier
Par défaut : 0
assert
Vérifier que l’utilisateur est connecté lorsque la valeur est user, ou bien qu’il n’est pas connecté si elle est anon, ou encore qu’il a le droit d’un utilisateur robot lorsque la valeur est bot.
Une des valeurs suivantes : anon, bot, user
assertuser
Vérifier que l’utilisateur actuel est l’utilisateur nommé.
Type : utilisateur, par nom d’utilisateur
requestid
Toute valeur fournie ici sera incluse dans la réponse. Peut être utilisé pour distinguer des demandes.
servedby
Inclure le nom d’hôte qui a renvoyé la requête dans les résultats.
Type : booléen (détails)
curtimestamp
Inclure l’horodatage actuel dans le résultat.
Type : booléen (détails)
responselanginfo
Inclure les langues utilisées pour uselang et errorlang dans le résultat.
Type : booléen (détails)
origin
En accédant à l’API en utilisant une requête AJAX inter-domaines (CORS), indiquez le domaine d’origine dans ce paramètre. Celui-ci doit être inclus dans toute requête de pré-envol et doit donc faire partie de l’URI de la requête (pas du corps du POST). Pour les requêtes authentifiées, il doit correspondre exactement à une des origines dans l’entête Origin, il doit donc être fixé avec quelque chose comme https://en.wikipedia.org ou https://meta.wikimedia.org. Si ce paramètre ne correspond pas à l’entête Origin, une réponse 403 sera renvoyée. Si ce paramètre correspond à l’entête Origin et l’origine indiquée est en liste blanche, l’API renseignera en réponse les entêtes Access-Control-Allow-Origin et Access-Control-Allow-Credentials. Pour les requêtes non authentifiées, indiquez la valeur *. L’API renseignera l’entête Access-Control-Allow-Origin dans sa réponse, mais Access-Control-Allow-Credentials vaudra false et toutes les données spécifiques à l’utilisateur seront filtrées.
uselang
Langue à utiliser pour les traductions de message : utilisez la requête de l’API action=query&meta=siteinfo avec siprop=languages pour renvoyer une liste de codes de langue, sinon indiquez user pour utiliser la langue préférée de l’utilisateur actuel, ou bien content pour utiliser la langue du contenu de ce wiki.
Par défaut : user
errorformat
Format à utiliser pour la sortie du texte d’avertissement et d’erreur.
plaintext
wikitexte sans aucun balisage HTML et avec les entités remplacées.
wikitext
wikitexte avec son balisage en syntaxe wiki non analysée.
html
wikitexte analysé et mis en forme en HTML uniquement.
raw
clé de message et paramètres.
none
aucune sortie de texte, uniquement les codes erreur.
bc
ancien format utilisé avant MediaWiki 1.29. errorlang et errorsuselocal sont ignorés.
Une des valeurs suivantes : bc, html, none, plaintext, raw, wikitext
Par défaut : bc
errorlang
Langue à utiliser pour les avertissements et les erreurs. Spécifier un des codes langues utilisables renvoyés par action=query&meta=siteinfo avec siprop=languages, sinon content pour utiliser la langue du contenu de ce wiki, ou encore uselang pour utiliser la même valeur que le paramètre uselang (la langue préférée pour l’interface utilisateur).
Par défaut : uselang
errorsuselocal
S’il est fourni, les textes d’erreur utiliseront des messages adaptés à la langue dans l’espace de noms MediaWiki.
Type : booléen (détails)

Exemples :

Aide pour le module principal
api.php?action=help [ouvrir dans le bac à sable]
Toute l’aide sur une page.
api.php?action=help&recursivesubmodules=1 [ouvrir dans le bac à sable]

Autorisations :

writeapi
Utiliser l'API de modification du wiki
Accordé à : all, user et bot
apihighlimits
Utiliser des valeurs plus hautes dans les requêtes de l’API (requêtes lentes : 500 ; requêtes rapides : 5000). Les limites pour les requêtes lentes s’appliquent aussi aux paramètres multivalués.
Accordé à : bot et sysop

Type de données[modifier | modifier le wikicode]

Les entrées dans MediaWiki doivent être en UTF-8 normalisé NFC. MediaWiki peut tenter de convertir les autres entrées, mais cela peut faire échouer certaines opérations (comme des modifications de pages avec les contrôles MD5).

Les paramètres qui prennent plusieurs valeurs sont normalement soumis avec les valeurs séparées par des barres verticales, par ex. param=valeur1|valeur2 ou param=valeur1%7Cvaleur2. Si une valeur doit contenir une barre verticale, utiliser U+001F (Séparateur Unix) comme séparateur et préfixer la valeur par U+001F, par ex. param=%1Fvaleur1%1Fvaleur2.

Certains types de paramètre dans les requêtes de l’API ont besoin de plus d’explications :

boolean
Les paramètres booléens fonctionnent comme des cases à cocher HTML : si le paramètre est spécifié, quelle que soit sa valeur, il est considéré comme vrai. Pour une valeur fausse, omettre complètement le paramètre.
expiry
Valeurs d’expiration relatives (par ex. 5 months ou 2 weeks) ou absolues (par ex. 2014-09-18T12:34:56Z). Pour ne pas avoir d’expiration, utiliser infinite, indefinite, infinity ou never.
timestamp
Les horodatages peuvent être spécifiés sous plusieurs formes, voir les formats d’entrée de la bibliothèque Timestamp documentés sur mediawiki.org pour plus de détails. La date et l’heure ISO 8601 sont recommandés : 2001-01-15T14:56:00Z. De plus, la chaîne now peut être utilisée pour spécifier l’horodatage courant.

Paramètres de modèle[modifier | modifier le wikicode]

Les paramètres de modèle supportent les cas où un module d’API a besoin d’une valeur pour chaque valeur d’un autre paramètre quelconque. Par exemple, s’il y avait un module d’API pour demander un fruit, il pourrait avoir un paramètre fruits pour spécifier quels fruits sont demandés et un paramètre de modèle {fruit}-quantité pour spécifier la quantité demandée de chaque fruit. Un client de l’API qui voudrait une pomme, cinq bananes et vingt fraises pourrait alors faire une requête comme fruits=pommes|bananes|fraises&pommes-quantité=1&bananes-quantité=5&fraises-quantité=20.

Remerciements[modifier | modifier le wikicode]

Développeurs de l’API :

  • Yuri Astrakhan (créateur, développeur en chef de sept. 2006 à sept. 2007)
  • Roan Kattouw (développeur en chef de sept. 2007 à 2009)
  • Victor Vasiliev
  • Bryan Tong Minh
  • Sam Reed
  • Brad Jorsch (développeur en chef depuis 2013)

Veuillez envoyer vos commentaires, suggestions et questions à [email protected] ou remplir un rapport de bogue sur https://phabricator.wikimedia.org/.