API:FAQ

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:FAQ and the translation is 84% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Ido • ‎Limburgs • ‎Nederlands • ‎Tiếng Việt • ‎Türkçe • ‎bosanski • ‎català • ‎dansk • ‎español • ‎français • ‎hrvatski • ‎italiano • ‎kurdî • ‎occitan • ‎polski • ‎português • ‎português do Brasil • ‎sicilianu • ‎suomi • ‎svenska • ‎čeština • ‎беларуская • ‎беларуская (тарашкевіца)‎ • ‎български • ‎русский • ‎українська • ‎العربية • ‎فارسی • ‎हिन्दी • ‎অসমীয়া • ‎মেইতেই লোন্ • ‎ಕನ್ನಡ • ‎ไทย • ‎中文 • ‎日本語 • ‎粵語 • ‎한국어
Cette page est en cours de rédaction.

Veuillez lire également la API:Page principale . Elle répond à quelques questions qui n'ont pas leur réponse ici et pointe vers d'autres pages utiles.

Comment puis je faire pour...

obtenir de l'aide ?

  1. Lire cette FAQ
  2. Essayer de trouver la réponse à votre question dans la documentation de l'API ici ou sur la page d'accueil de l'API avec documentation intégrée
  3. Si vous n'arrivez pas à trouver votre réponse sur le web,

Signaler une anomalie (bogue) ou demander une fonctionnalité ?

Si vous avez trouvé un bug dans l'API ou voulez faire une requête pour une nouvelle fonctionnalité, reportez-le sur Phabricator. Cherchez parmi les bugs existants d'abord, ne dupliquez pas les rapports sur un même bug, et entrez MediaWiki-API comme projet en reportant un nouveau bug à propos de l'API. Si la fonctionnalité que vous demandez ou reportez est offerte par une extension (exemples : AbuseFilter ou FlaggedRevs), ajoutez le projet lié à cette extension, soit "MediaWiki-extensions-AbuseFilter" dans l'exemple précédent.

Trouver quelle action ou sous-module utiliser ?

L'API de MediaWiki est vaste, et les extensions l'agrandisse encore. Quelques suggestions :

  • Si vous essayez d'obtenir une information à propos d'une page, vous devrez probablement utiliser un sous-module prop= de action=query. Les autres sous-modules de l'action « query » renvoient des listes de pages ou des méta-informations à propos du wiki. Regardez l'aide auto-générée de l'API sur tous les sous-module pour plus d'informations.
  • Si vous voyez une page faire quelque chose d'intéressant après le chargement initial, une requête vers l'API a dû être utilisée.
    • Ouvrez la console de votre navigateur et cherchez les requêtes envoyées sur le réseau vers api.php.
    • Tous les codes utilisés par les wikis Wikimedia sont open source, vous pouvez donc lire les codes sources faisant les requêtes API. Une technique pour trouver la source est d'ajouter ?uselang=qqx à l'URL de la page wiki pour voir les messages clé avec les résultats que l'API a retournés. Vous pouvez ensuite chercher ces noms de messages dans les fichiers des messages internationalisés i18n/en.json du noyau MediaWiki ou des extensions.
  • Vous pouvez voir la totalité de l'aide auto-générée de l'API sur une seule page en ajoutant recursivesubmodules=1, comme ceci.

Les liens vers l'aide auto-générée de l'API au-dessus vont à la version anglaise de Wikipedia. Vous devriez utiliser l'aide du wiki où vous ferez des requêtes API, étant donné que chaque wiki possède une configuration et des extensions différentes.

appeler l'API ?

Envoyer des requêtes HTTP vers api.php. Par exemple, sur la version anglaise de Wikipedia, l'URL à utiliser est https://en.wikipedia.org/w/api.php . La plupart des wikis possèdent une URL similaire : mettez simplement api.php à la place de index.php en réalisant une action sur la page (regarder l'historique, modifier...). Depuis la version 1.17, MediaWiki supporte Really Simple Discovery; le code source HTML de chaque page possède un lien RSD pointant vers un descriptif RSD où trouver l'API. L'adresse de l'API peut aussi être trouvée sur la page Special:Version de chaque wiki. Si vous ne parvenez pas à trouver l'URL de api.php sur un wiki indépendant (qui ne tourne pas sous Wikimedia), contactez son propriétaire. Il est possible que l'API MediaWiki soit désactivée, voir $wgEnableAPI.

For example, on the English Wikipedia, the URL is https://en.wikipedia.org/w/api.php . Most wikis have api.php at a similar URL: just use api.php in place of index.php in page actions. From 1.17 onwards, MediaWiki supports Really Simple Discovery; the HTML source of every page has an RSD link pointing to an RSD descriptor which indicates where to find the API. If you can't figure out the URL of api.php on a third-party (non-Wikimedia-operated) wiki, contact its owner. The wiki may not enable the MediaWiki API, see $wgEnableAPI.

Pour découvrir l'API

  • utilisez Special:ApiSandbox ;
  • ouvrez la console de votre navigateur et observez les requêtes envoyées vers api.php pendant que vous interagissez avec le wiki.

contrôler le format de sortie ?

Passez &format=someformat dans les paramètres de la requête. Pour plus d'information, voir la liste des formats de sortie.

vérifier si un module de l'API est disponible ?

Vous pouvez utiliser action=paraminfo pour demander des informations à propos des modules et des sous-modules de l'API (comme query+geosearch) dont vous avez besoin. Le tableau paraminfo.modules contenu dans le résultat doit contenir une clé nommée path pour chaque module et sous-module. Si elle n'est pas présente, c'est que la fonctionnalité est indisponible.

The paraminfo.modules array in the response must contain a path key for each module and submodule, anything missing is not available.

Si un module de l'API est indisponible et vous savez de quelle extension il provient, vous pouvez vérifier si cette extension est chargée en utilisant la méta-information siteinfo avec siprop=extensions et voir si son nom figure dans la liste renvoyée.

Même si un module apparaît comme disponible, vous devez toujours gérer les erreurs de l'API.

détecter les erreurs ?

Plus d'informations sur Erreurs et avertissements.

Si l'API renvoie une erreur comme réponse, le header HTTP MediaWiki-API-Error sera défini et une structure error s'affichera sur la page. Pour un exemple d'erreur, allez sur https://en.wikipedia.org/w/api.php?action=blah.

obtenir le contenu d'une page en wikitexte ?

Si vous voulez simplement le wikitexte brut sans la moindre autre information, le mieux est d'utiliser le mode action=raw sur index.php à la place de l'API: https://en.wikipedia.org/w/index.php?action=raw&title=Main_Page. Notez que cela retournera le wikitexte pur sans aucun formatage. Voir aussi la documentation de action=raw .

Pour avoir plus d'informations sur la page et sa dernière version, utilisez l'API : https://en.wikipedia.org/w/api.php?action=query&prop=revisions&titles=Main_Page. Voir aussi la documentation du module prop=revisions .

Vous pouvez récupérer 50 (5 000 pour les administrateurs et les robots) pages par requête d'API : https://en.wikipedia.org/w/api.php?action=query&prop=revisions&rvprop=content&titles=Main_Page%7CArticles. Cette méthode peut aussi être utilisée avec les générateurs.

obtenir le contenu d'une page en HTML ?

Si vous voulez uniquement le code HTML, le mieux est d'utiliser le mode action=render de index.php au lieu de l'API : https://en.wikipedia.org/wiki/Main_Page?action=render.

Voir la documentation action=render .

Avec l'arrivée de RESTBase, vous pouvez désormais demander la dernière version HTML en cache d'une page sur les wikis Wikimedia. Exemple : https://en.wikipedia.org/api/rest_v1/page/html/Main_Page à l'inverse de ?action=render retourne un document HTML complet (c'est à dire <html><head>différentes métadonnées</head><body>...</body></html> ); vous pouvez utiliser une bibliothèque d'analyse HTML pour obtenir le contenu le plus indenté de la balise <body> (voir la documentation).

Pour avoir davantage d'informations fournies par le texte wiki au moment de l'analyse (liens, catégories, sections, etc.), vous pouvez :

gérer les changements de l'API de 2015 ?

Le comportement par défaut pour continuer une requête a changé avec la version 1.26 de MediaWiki. Si vous désirez des données supplémentaires sur l'information de continuation de la réponse de requête API, « vous devez mettre à jour votre code ». Soit :

De plus, depuis MediaWiki 1.25, une structure de résultat améliorée pour les formats JSON et PHP est utilisable en ajoutant formatversion=2 à vos requêtes. En juillet 2015, cette fonctionnalité était toujours considérée expérimentale car certains modules de l'API pourraient encore être améliorés dans ce mode. Si vous êtes prêt à prendre le risque de devoir faire d'autres changements dans le futur, il est bien mieux d'utiliser formatversion=2 pour traiter les résultats de l'API.

Pourquoi...

je reçois une erreur HTTP 403 ?

Ceci pourrait signifier que vous ne passez pas un entête HTTP de User-Agent ou que votre User-Agent est vide ou se trouve en liste noire de m:User-Agent policy. Voir API:Client code pour plus d'information. Aussi, cela pourrait signifier que vous passez & dans la chaîne de commande d'une requête GET: Wikimedia bloque tous ces types de requêtes, à la place utilisez POST pour cela.

je reçois une erreur readapidenied ?

Le wiki sur lequel vous effectuez la requête contient du contenu privé et nécessite que les utilisateurs soient connectés pour pouvoir lire toutes les pages. Cela signifie qu'un client doit être connecté pour interroger n'importe quelle information par l'API. Voir API:Login pour plus d'informations. Il n'est actuellement pas possible de demander le contenu des pages de la liste blanche sans se connecter, même si elles sont accessibles par l'interface utilisateur habituelle.

je reçois une erreur de mauvais jeton ?

Cette erreur est souvent causée par une absence de jeton dans la requête (voir à propos des jetons dans la documentation du module que vous utilisez) ou des problèmes à rester connecté. Il est également possible que vous réutilisez un type de jeton qui ne peut pas l'être (voir la documentation du module pour les détails) ou que le jeton utilisé est associé à une session expirée. En général, quand des jetons cachés sont utilisés, récupérer un nouveau jeton (voir API:Tokens) et essayer encore avant d'abandonner.

je reçois des avertissements à la place des jetons (l'action 'modifier' n'est pas accordée à l'utilisateur actuel) ?

Soit vous n'avez pas le droit nécessaire pour effectuer l'action liée à la requête, soit vous avez des problèmes pour rester connecté.

je reçois une erreur mustposttoken ?

L'action que vous tentez d'effectuer doit utiliser HTTP POST. Vous avez probablement cliqué sur l'URL de api.php dans un navigateur ou modifié une URL existante dans la barre d'adresse de votre navigateur, mais cela produit une requête HTTP GET. Vous devrez utiliser une librairie (comme le module ResourceLoader de mediawiki.api) ou tout autre outil pouvant exécuter des requêtes POST; généralement vous devrez également renseigner les cookies de votre session et un jeton pour que MediaWiki puisse vérifier que vous êtes un utilisateur connecté avec les droits nécessaires pour effectuer cette action. Pour contourner le problème, vous pouvez tenter d'utiliser l'outil en ligne de commande cURL, en renseignant chaque paramètre de l'API avec -F 'action=delete' -F 'token=hexadecimal stuff+\' et les cookies nécessaires du navigateur avec -H 'Cookie:your session cookies'. La partie « Réseau » ou « Network » des outils de développement du navigateur (Ctrl+Shift+I) de Firefox et chromium possède une option de menu « Copier comme cURL » qui peut aider, mais cela reste délicat.

Selon ce que vous voulez faire, il est possiblement plus simple d'apprendre à utiliser un robot ou une librairie gérant les détails de la session, des cookies, et des jetons pour vous.

est-ce qu'une fonctionnalité X n'est pas disponible via l'API ?

Toutes les fonctionnalités disponibles sur l'interface utilisateur ne le sont pas sur l'API. Celles-ci n'ont pas été implémentées soit parce que personne ne s'en est occupé pour le moment ou parce que personne n'a demandé à ce qu'elles soient ajoutées. Pour plus d'informations sur al manière de proposer une nouvelle fonctionnalité, voir ci-dessus.

est-ce que ma requête API sur les wikis Wikimedia retourne simplement une erreur HTML ?

Si vous utilisez des appels à l'API avec des requêtes POST, assurez-vous que ces requêtes n'utilisent pas Content-Type: multipart/form-data. Cela se produit par exemple quand vous utilisez CURL pour accéder à l'API et que vous passez les paramètres POST dans un tableau. Les serveurs proxy de Squid sont utilisés comme serveurs frontaux dans la ferme des wikis de Wikimedia ne gèrent pas cela correctement, c'est pourquoi une erreur est retournée.

À la place, utilisez la notation "value1=key1&value2=key2..." pour passer les paramètre comme une chaîne de caractères, similairement aux requêtes GET.

Sur les autres wikis auxquels vous accédez directement, cela ne fait pas de différence.

En plus, certains logiciels (comme cURL) envoient un entête Expect: 100-continue pour des requêtes POST plus longues (>1024 octets). Les wikis Wikimedia passant par les serveurs Squid ne reconnaissent pas cela. Si vous avez encore des erreurs HTML avec les requêtes POST, et n'êtes pas connecté, essayez de déclarer un entête vide attendu (c'est à dire utiliser cURL en ligne de commande et mettre l'option --header 'Expect:').

les URL très longues vers l'API ne fonctionnent pas ?

Il existe une taille maximale pour les URL lorsque vous faites des requêtes GET vers l'API. Cette limite varie selon le site. La limite de Wikimedia est aux alentours de 8 100 caractères. Si vous vous approchez de cette limite, utilisez des requêtes POST à la place (vous devrez peut-être aussi définir l'en-tête Expect, comme décrit ci-dessus).