Qu'est-ce qu'une API ?

Une API est un acronyme pour Application Programming Interface. Cela permet à différentes applications de communiquer les unes avec les autres. Parfois, une API permet à une application de demander à celle qui implémente l'API de réaliser une action. Dans les termes généraux de MediaWiki, il s'agit d'APIs basées sur le web, qui utilisent le mécanisme de requête-réponse HTTP et produisent des données structurées JSON/XML.

Qu'est-ce qu'une API REST ?

REST est un acronyme pour REpresentational State Transfer. Un système RESTful est définit par un ensemble de principes fondamentaux ou contraintes. Une API RESTful (ou juste API REST) adhère à ces principes et s'avère ainsi être un service plus rapide, fiable et flexible.

Que peuvent faire les APIs ?

Voir quelques exemples d'utilisations d'APIs.

Où puis-je en apprendre plus sur les APIs ?

Voici quelques ressources :

• APIs Web - Comprendre les APIs
• Une introduction aux APIs
• REST - APIs REST (REpresentational State Transfer)

L'API Action de MediaWiki, c'est quoi ?

L'API Action de MediaWiki est un service webRESTful qui permet aux utilisateurs de réaliser certaines actions sur un wiki telles que la création de pages, l'authentification, l'analyse syntaxique, la recherche, etc.

À quoi peut servir l'API Action de MediaWiki ?

L'API Action de MediaWiki peut être utilisée pour :

• avoir accès aux fonctionnalités d'un wiki.
• intéragir avec un wiki.
• obtenir des métadonnées sur des wikis et leurs utilisateurs publics.

La barre latérale droite indique de nombreuses fonctionnalités prises en charge par l'API. Voir aussi quelques projets Wikimédia qui utilisent l'API Action de MediaWiki.

Comment utiliser (ou appeler) l'API Action de MediaWiki ?

Des requêtes HTTP sont généralement utilisées pour appeler l'API Action. Pour des instructions plus détaillées, se référer au tutoriel.

Pour expérimenter l'API Action :

• utilisez Special:ApiSandbox ;
• activez la console de développement de votre navigateur et observez les requêtes réseau vers api.php tout en interagissant avec le wiki.

Qu'est-ce qu'un module, un sous-module et un paramètre ?

L'API Action de MediaWiki possède de nombreux modules que nous utilisons pour réaliser différentes tâches. Avec des termes techniques, un module est une sous-classe d'ApiBase. Un module nécessite des paramètres. Ces paramètres peuvent (ou non) être des sous-modules.

Prenons la requête suivante :

ici :

• action est un paramètre du module principal.
• action=query est un autre module. Il est appelé le module requête (query).
• list est un paramètre du module requête.
• list=search est aussi un module. Il peut être appelé sous-module de recherche (query) de action=query.
• srsearch est un paramètre du module de recherche. Il contient la chaîne de recherche 'abc'.
• format est un paramètre du module principal.
• json est le format de sortie.

Aussi, voir Introduction et règles de conduite, qui décrit les sous-modules du module action=query .

Comment savoir quel module et sous-module appeler ?

L'API Action de MediaWiki est vaste, et les extensions l'agrandissent encore. Voici quelques méthodes pour préparer votre requête d'API :

• Dans la barre de navigation latérale, recherchez les fonctionnalités que vous souhaitez implémenter et cliquez sur le lien pour obtenir des informations sur les modules à appeler.
• Les pages de l'API documentées automatiquement contiennent une liste de tous les modules et sous-modules avec de courtes descriptions. Vous pouvez commencer par le module principal puis cliquer sur les liens vers les différents sous-modules. (Ajoutez recursivesubmodules=1 pour voir la version étendue)

Où trouver des exemples de code sur l'utilisation des modules de l'API ?

Les pages de documentation de l'API contiennent une section « Exemples » pour présenter comment utiliser différents modules et sous-modules. La documentation générée automatiquement contient aussi des exemples basés sur les descriptions des modules.

Voir Mediawiki-API-demos pour des extraits de code en Python et JavaScript.

Comment contrôler le format de sortie ?

Le format de sortie par défaut est JSON. Les autres formats de sortie ont été dépréciés ou supprimés dans la dernière version stable de MediaWiki, et leur utilisation est déconseillée.

Dans les vieilles versions, pour contrôler le format de sortie, vous pouvez ajouter &format=someformat dans la chaîne de requête.

Pour d'autres informations, API:format de données.

Faut-il un jeton d'accès ?

Vous aurez besoin d'un jeton d'accès pour effectuer des actions de modification des données telles que la connexion, l'édition, le déplacement de pages, etc.

Pour en savoir plus, consultez API:Tokens ou la catégorie de la barre latérale « Authentification ».

Comment faire des requêtes inter-sites en utilisant l'API ?

Vous devez utiliser JSONP ou CORS pour faire des requêtes inter-sites sur MediaWiki.

Pour plus de détails, consultez API:Requêtes entre différents sites.

Les résultats des requêtes ont-ils une limite ?

Oui, cela dépend du paramètre query. Par exemple, les requêtes utilisant list ou property ne peuvent pas fournir plus de 500 résultats pour des utilisateurs classiques. Les pages de l'API contiennent des information sur ces limites dans les sections « Notes supplémentaires » ou « Limites ». Notez que certains modules imposent des limites plus strictes dans certaines conditions.

Si vous n'êtes pas sûr de la limite à fixer et que vous voulez obtenir le plus de résultats possible, fixez la limite à max.

Y-a-t-il une limite sur les appels à l'API ?

Il n'y a pas de limite concrète. Cependant, nous recommendons de faire un nombre raisonnable d'appels pour éviter d'être bloqué. Si vous voulez faire des requêtes en masse, contactez les administrateurs en premier lieu.

Aussi, voir API:Etiquette.

Où trouver les mises à jour de l'API Action de MediaWiki ?

Vous pouvez vous abonner à la liste de diffusion MediaWiki-API-Announce pouyr être mis au courant des annonces et mises à jour.

Les dumps wiki c'est quoi ? et comment travailler avec

Les dumps Wikimedia sont des dumps pour un wiki des collections, du contenu, des métadonnées, des indices de recherche, etc. Pour travailler avec, voir comment les utiliser et les dumps publics.

Où trouver de l'aide supplémentaire ?

Si vous ne trouvez pas de réponses dans la documentation de l'API de MediaWiki ou sur les pages de la documentation générée automatiquement, n'hésitez pas à prendre contact de l'une des manières suivantes.

• Créer un compte Wikimedia (si vous n'en n'avez pas déjà un) et ajoutez un sujet sur la page de discussion de l'API.
• Posez votre question sur :
  • IRC dans le canal #mediawiki ^connecter.
  • la liste de diffusion MediaWiki-API.

Comment créer un module d'API dans une extension ?

API:Extensions vous guidera à travers le processus complet de la création d'un module d'API dans une extension.

Quelle est la structure interne de l'API ?

API:Stratégie d'implémentation explique l'implémentation des systèmes de l'API dans MediaWiki Core.

Comment limiter l'utilisation de l'API ?

Pour limiter l'utilisation de l'API, vous vous pouvez soit limiter l'utilisation de l'API d'écriture ou désactiver des modules individuellement.

Pour plus des instructions et des exemples, consultez API:Limiter l'utilisation de l'API.

Comment détecter une erreur ?

Si vous faîtes face à une erreur, la réponse d'erreur de l'API fixera l'entête HTTP MediaWiki-API-Error et renverra une structure d'erreur.

Que signifie cette erreur ?

Trouvez l'erreur dans la liste des messages d'erreur standards pour comprendre ce qu'elle signifie.

Comment déclarer un bogue ou une demande de fonctionalité ?

Vous pouvez déclarer des bogues ou des demandes de fonctionnalités sur l'outil de suivi des tâches de Wikimedia, Phabricator.

Note :

• Ajoutez la balise de projet MediaWiki-API à votre tâche.
• Si votre signalement vou demande est proposée par une extension, ajoutez le projet de cette extension (p. ex. MediaWiki-extensions-AbuseFilter, MediaWiki-extensions-FlaggedRevs, etc.).
• Vérifiez l'existence de duplicats avant de créer une nouvelle tâche.
• Renseignez-vous sur les termes de création d'une tâche sur Phabricator avant de commencer.

Consultez Comment signaler une anomalie du logiciel (bogue) pour plus de détails.

Mes erreurs viennent-elles d'un problème de version d'API ?

Si un site web tourne sous une version différente de MediaWiki, il tourne aussi sous une version différente de l'API. Certains paramètres de modules pris en charge dans une version peuvent être dépréciés (ou supprimés) dans d'autres. Ces paramètres lèveront une exception lorsqu'utilisés. Les pages de l'API documente de telles dépréciations.

Consultez les notes de publication pour obtenir des informations sur les différentes versions de l'API.