API:API REST

L' API REST vous permet d'interagir avec MediaWiki en envoyant des requêtes HTTP vers des URLs rest.php. Vous pouvez utiliser l'API pour construire des applications et des scripts qui exécutent des recherches et affichent des pages wiki, récupèrent des fichiers de médias, et exploitent l'historique des pages.

Démarrage rapide

# Rechercher un article à propos de la terre (Earth), sur la Wikipedia anglophone $ curl "https://en.wikipedia.org/w/rest.php/v1/search/page?q=earth&limit=1"

Essayez !

Formats des données

Les points d'accès de l'API REST renvoient les données au format JSON ou HTML. Voir les références de l'API pour le type de contenu pris en charge par chaque point d'accès.

Méthodes

L'API prend en charge les méthodes des requêtes HTTP usuelles.

GET	Récupérer la ressource
HEAD	Renvoie les entêtes HTTP pour une requête GET sans données dans la réponse
POST	Créer une ressource
PUT	Mettre à jour ou créer une ressource

Structure des URLs

Les points d'accès de l'API partagent une structure cohérente d'URL qui inclut l'URL de base du wiki, le chemin du script du wiki, et la version de l'API.

# structure de l'URL
[URL du projet]/[chemin du script]/rest.php/v[numéro de version]/

# Exemple d'URL : obtenir l'historique de la page d'accueil de la Wikipedia anglophone
https://en.wikipedia.org/w/rest.php/v1/page/Main_Page/history

Versions

Conçue pour fournir une stabilité à long terme pour les développeurs, l'API REST de MediaWiki est versionnée en utilisant un numéro de version global dans le chemin de l'API (par exemple : /v1/). D'après les principes de la sémantique des versions, cette dernière est incrémentée lorsqu'un point d'accès est modifié et qu'il ne soit plus possible de revenir en arrière, comme par exemple lors de la suppression d'une propriété de réponse ou de l'ajout d'un paramètre obligatoire. Avec une version majeure, l'API peut être modifiée de sorte à pouvoir revenir en arrière, comme par exemple ajouter une propriété de réponse ou un paramètre de requête optionnel.

/v1/ (dernière)	Disponible en MediaWiki 1.35

Droits et autorisations

L'API REST est conçue pour être utilisée avec l'extension OAuth pour l'authentification des utilisateurs et les permissions. Néanmoins, sans tenir compte de la méthode d'authentification, l'API répond à la présence d'un utilisateur connecté et renvoie le contenu autorisé par les droits de cet utilisateur.

Accès aux projets Wikimedia avec l'API REST

Vous pouvez utiliser l'API REST pour accéder à Wikipedia,au Wiktionnaire, et à d'autres projets Wikimedia dans diverses langues. Pour une liste complète des URLs des projets Wikimedia, voir la matrice des sites Meta-Wiki.

Limitation des requêtes

Il n'existe aucune limite fixée quant aux requêtes de l'API, mais votre client peut être bloqué si vous attentez à la stabilité d'un site. Pour rester à un niveau sécuritaire de requête, attendez que chaque requête se termine avant d'envoyer la requête suivante.

Identification des clients

Les sites Wikimedia nécessitent un entête d'agent utilisateur HTTP pour chaque requête d'API. Cela permet d'identifier votre application et de s'assurer que les administrateurs système peuvent vous contacter si un problème apparait. Les clients qui émettent des requêtes sans utiliser l'entête des agents utilisateurs peuvent voir leur adresse IP bloquée sans préavis.

L'entête de l'agent utilisateur peut contenir une page utilisateur du wiki local, d'un autre wiki relatif en utilisant la syntaxe des liens interwikis, une URL de site web externe appropriée, ou une adresse courriel.

# Format préféré pour les entêtes des agents utilisateurs
<nom du client>/<version> (<nous contacter>) <nom de bibliothèque / environnement>/<version>

Si l'API est appelée à partir du JavaScript de votre navigateur, il est possible que vous ne puissiez pas intervenir sur l'entête de l'agent utilisateur (cela dépend du navigateur). Pour contourner cela, utilisez l'entête Api-User-Agent. Voir la politique des agents utilisateur de Meta-Wiki pour plus d'information.

Autorisation

Pour autoriser votre application à agir pour le compte d'un utilisateur, suivez le guide du développeur OAuth pour l'enregistrer et faire des requêtes en utilisant les jetons OAuth.

Licences et marques commerciales

Le contenu Wikimedia est libre d'être réutilisé sous les termes spécifiés par la licence utilisée. Les licenses peuvent être différentes selon les projets, donc vérifiez les projets individuels pour les informations relatives aux licences et la réutilisation du contenu. Par exemple, le texte de la Wikipedia anglophone peut être utilisé selon les termes de la licence Creative Commons Attribution Share-Alike, alors que les fichiers de média de Wikimedia Commons ont des licences individuelles tel qu'indiqué sur la page d'information des fichiers. Pour d'autres informations concernant l'utilisation de la licence et des marques commerciales, voir recommandations MetaWiki pour les développeurs d'applications.

Limites de Wikidata

Alors que l'API REST est disponible dans les projets Wikimedia, elle n'est pas complètement prise en charge par Wikidata. Au moment où nous écrivons ces lignes, certains des points d'accès peuvent renvoyer des erreurs inattendues. Remplacer par l'API Wikidata REST.

Point d'accès des extensions

Les extensions MediaWiki peuvent couvrir les points de terminaison de l'API spécifiques aux extensions en utilisant l'interface REST API. Voir les documents d'interface de l'extension de l'API REST pour débuter. Pour la documentation sur les points d'accès de l'API REST fournis par les extensions, voir les documents des extensions. L'interface de l'extension API REST est disponible dans MediaWiki 1.34 via $wgEnableRestAPI et dans MediaWiki 1.35 et ultérieur par défaut.

Comparaison des API

API	Disponibilité	Base de l'URL	Exemple
API Action de MediaWiki	Inclus dans MediaWiki Activé sur les projets Wikimedia	/api.php	https://fr.wikipedia.org/w/api.php?action=query&prop=info&titles=Terre
API REST de MediaWiki	Inclus dans MediaWiki 1.35+ Activé sur les projets Wikimedia	/rest.php	https://fr.wikipedia.org/w/rest.php/v1/page/Terre
Wikimedia REST API	Non inclus dans MediaWiki Disponible uniquement dans les projets Wikimedia	/api/rest	https://fr.wikipedia.org/api/rest_v1/page/title/Terre
Pour des API des projets Wikimedia dimensionnés pour un usage commercial, suivez le lien Wikimédia Enterprise

À propos de ces documents

Ces documents ont été écrits manuellement en se basant sur le code source du noyau MediaWiki. Les corrections et les ajouts restent les bienvenus ! Pour partager un tutoriel ou une application qui utiliser l'API REST de MediaWiki, ajoutez un lien au modèle REST API.

Voir aussi

• REST API sur Wikipedia.
• Page de l'initiative de l'API REST
• Manuel:$wgRestPath

• Maintenu par MediaWiki Interfaces Team.
• Discussion en direct (IRC): #mediawiki-core ^connecter
• Suivi des problèmes : Phabricator MediaWiki-Action-API (rapporter un problème)