API:FAQ/fr

Voir également le guide de démarrage rapide. Il réponds à quelques questions qui n'ont pas de réponse ici et pointe également vers diverses pages utiles.

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,
 * 4) * vous pouvez la poser sur la liste de diffusion par mail mediawiki-api.
 * 5) * 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.
 * 6) * Demander sur IRC sur le canal du réseau Freenode.

Signaler une anomalie (bug) 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 . 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. Les chargement des suggestions de recherche est un exemple.
 * Ouvrez la console de votre navigateur et cherchez les requêtes vers.
 * 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  à l'URL de la page wiki (ou   si un point d'interrogation est déjà présent) pour voir les noms des messages systèmes liés aux requêtes faites. Vous pouvez ensuite chercher ces noms de messages dans les fichiers   du noyau MediaWiki ou d'une extension.
 * Vous pouvez voir la totalité de l'aide auto-générée de l'API sur une seule page en ajoutant, [ 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(S) vers  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  à la place de   en réalisant une action sur la page (regarder l'historique, modifier...). Depuis la version 1.17, MediaWiki supporte Really Simple Discovery; le code 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'accès à l'API sur un wiki indépendant, contactez son propriétaire. Il est possible que l'API MediaWiki soit désactivée, voir.

Pour découvrir l'API :


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

contrôler le format de sortie ?
Rajoutez  dans les paramètres de la requête. Pour plus d'informations, voir la liste des formats de sortie. À noter qu'un travail est en cours pour retirer tous les formats à l'exception de JSON, et il s'agit donc du format à utiliser dès que possible.

vérifier si un module de l'API est disponible ?
Vous pouvez utiliser  pour trouver des informations à propos des modules et sous-modules de l'API (comme  ) dont vous avez besoin. Le tableau  contenu dans le résultat doit contenir une clé nommée   pour chaque module et sous-module. Si elle n'est pas présente, c'est que la fonctionnalité est indisponible.

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  et voir si son nom est présent ou non dans la liste affichée.

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

détecter des erreurs ?
Plus d'informations sur Erreurs et avertissements.

Si l'API renvoie une erreur comme réponse, le header HTTP  sera défini et une structure   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. Cela retournera le wikitexte pur sans aucun formatage. Voyez aussi la documentation sur cette méthode.

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. La documentation sur le sous-module prop=revisions vous renseignera à ce sujet.

Vous pouvez récupérer 50 (5 000 pour les administrateurs et les robots) pages par requête : https://en.wikipedia.org/w/api.php?action=query&prop=revisions&rvprop=content&titles=Main_Page|Articles. 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, utiliser le mode  de index.php est la meilleure solution : https://en.wikipedia.org/wiki/Main_Page?action=render. Regardez la documentation pour plus de détails.

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://rest.wikimedia.org/en.wikipedia.org/v1/page/html/Main_Page (pour des raisons de performance, cette fonctionnalité est aussi accessible depuis https://en.wikipedia.org/api/rest_v1/page/html/Main_Page afin de réutiliser un réseau de connexions existantes vers le wiki). Au contraire de  cela retourne un document HTML complet ; vous pouvez utiliser une librairie d'analyse HTML pour obtenir le contenu de la balise   (voir la documentation).

Pour avoir des informations sur des éléments précis contenus dans le wikitexte (liens, catégories, sections, etc.), vous pouvez :


 * Faire une requête avec un des sous-modules de propriétés qui vous apportera les informations désirées (liens, catégories, etc.).
 * Utiliser le module  :

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 qui sont la continuation d'une requête API, vous devez mettre à jour votre code. Soit :
 * ajouter  à vos requêtes pour continuer à obtenir l'ancien comportement, peu clair
 * ou ajouter  à vos requêtes et mettre à jour votre code pour s'adapter au nouveau comportement, plus propre, disponible depuis MediaWiki 1.21.

De plus, depuis MediaWiki 1.25, une structure de résultat améliorée pour les formats JSON et PHP est utilisable en ajoutant   aux 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.

je reçois une erreur erreur HTTP 403 ?
This could mean you're not passing a  HTTP header or that your   is empty or blacklisted User-Agent policy. See the quick start guide for more information. Also, it could mean that you're passing  in the query string of a GET request: Wikimedia blocks all such requests, use POST for them instead.

do I get the readapidenied error?
The wiki you're querying contains private content and requires users to log in in order to be able to read all pages. This means that a client needs to be logged in to query any information at all through the API. See the quick start guide for more information. It's not currently possible to query the contents of whitelisted pages without logging in, even though they're available in the regular user interface.

do I get badtoken errors?
This is usually because you're either not passing a token at all (read about tokens in the documentation of the module you're using) or because you're having trouble staying logged in. It's also possible you're reusing a type of token that can't be reused (see module documentation for details) or that you're using a token that's associated with an expired session. In general, when using cached tokens, refetch the token (see API:Tokens) and try again before giving up.

do I get warnings instead of tokens (Action 'edit' is not allowed for the current user)?
You either don't have the right to execute the action you requested, or you're having trouble staying logged in.

do I get mustposttoken error?
The action you're attempting must be requested using HTTP POST. You probably clicked on  URL in a browser or modified an existing URL in the browser's location field, but that results in an HTTP GET request. You have to use a library (such as the mediawiki.api ResourceLoader module) or utility that can make POST requests; usually you also have to provide it your session cookies and an API:token so MediaWiki can verify that you are the logged-in user with rights to perform the action. As a hack, you might be able to use the cURL command-line utility, providing it each API parameter with  and the necessary browser cookies with. The Network panel of the browser developer tools window (Ctrl+Shift+I) in Firefox and chromium has a "Copy as cURL" menu item that can help, but it's still fiddly.

Depending on what you want to do it's easier to learn how to use a bot or library that handles the details of login, cookies, and tokens for you.

is X not available through the API?
Not all features available in the user interface are available through the API. Such features weren't implemented either because no one has gotten around to it yet or because no one has requested them. For information about filing feature requests, see above.

does my API call on Wikimedia wikis just return an HTML error?
If you use API calls with POST requests make sure that these requests don't use Content-Type: multipart/form-data. This happens for instance if you use CURL to access the API and you pass your POST parameters as an array. The Squid proxy servers which are used at frontend servers at the Wikimedia wiki farm don't handle that correctly, thus an error is returned.

Instead, use the "value1=key1&value2=key2..." notation to pass the parameters as a string, similar to GET requests.

On other wikis which you access directly it doesn't make a difference.

In addition, some software (such as cURL) send an  header for longer POST requests (>1024 bytes). The wikimedia wikis that go through Squid servers can't cope with this. If you are still getting HTML errors with post requests, and are not logged in, try setting a blank Expect header (e.g. using cURL on the command line, use the option ).

do really long API urls not work?
There is a maximum limit of the url size that can be used with the API when making GET requests. This limit varies depending on the website. Wikimedia's limit is roughly around 8100 characters. To get around this limit use POST requests instead (you may also need to set the Expect header, as described above)