API:Etiquette

Cette page contient les meilleures pratiques à suivre pour utiliser l'API. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

Comportement

Demande de limitation

Il n'existe pas de limites codées en dur et rapides pour les requêtes en lecture, mais réfléchissez bien et essayez de ne pas surcharger les sites. La plupart des administrateurs système se réservent le droit de vous bloquer tout simplement, si vous portez atteinte à la stabilité de leur site.

En envoyant vos requêtes en série plutôt qu'en parallèle, en attendant qu'une requête se termine avant d'envoyer la suivante, vous pouvez atteindre un taux de requêtes respectable. Nous recommandons aussi de regrouper plusieurs éléments dans une seule requête en :

• utilisant le caractère pipe (|) à chaque fois que cela est possible par exemple titles=PageA|PageB|PageC, au lieu de faire un nouvelle requête pour chaque titre.
• utilisant un générateur au lieu de faire une requête pour chaque résultat venant d'une autre requête.

• Utilisez la compression GZip lorsque vous faites des appels à l'API en initialisant Accept-Encoding: gzip pour réduire l'utilisation de la bande passante.

Le nombre de requêtes qui font des modifications, qui changent l'état ou autre et donc qui ne sont pas des requêtes en lecture seule, peut être limité par période de temps. La valeur exacte du seuil appliqué peut être fonction du type d'action, de vos droits utilisateur et de la configuration du site web à qui vous faites la requête. Les limites vous concernant peuvent être déterminées quand vous vous connectez au point d'accès de l'API action=query&meta=userinfo&uiprop=ratelimits.

api.php?action=query&format=json&meta=userinfo&uiprop=ratelimits [Essayez !]

Lorsque vous atteignez la limite correspondant au seuil des requêtes, vous recevrez une réponse en erreur de l'API avec l'erreur code ratelimited. Si vous rencontrez cette erreur, vous pouvez retenter cette requête, mais en augmentant le temps entre chaque requête. Une stratégie commune pour cela est l'Exponential backoff ^(en).

Analyser les révisions

Alors qu'il est possible d'obtenir des résultats pour un numéro de révision spécifique en utilisant le paramètre revid, ceci reste une opération coûteuse pour les serveurs. Pour récupérer une révision spécifique utilisez le paramètre oldid. Par exemple :

api.php?action=parse&format=json&prop=images&oldid=254862759 [Essayez !]

Paramètre maxlag

Si votre tâche n'est pas interactive (c'est à dire que l'utilisateur n'est pas bloqué sur l'attente du résultat) vous devez utiliser le paramètre maxlag . La valeur du paramètre maxlag doit être un nombre entier de secondes. Par exemple :

api.php?action=query&format=json&titles=Main%20Page&maxlag=1 [Essayez !]

Ceci empêche votre tâche de s'exécuter quand la charge des serveurs est importante. Les valeurs hautes impliquent un comportement plus aggressif, les valeurs basses sont plus agréables.

Voir Manuel:Paramètre maxlag pour plus de détails.

Entête de l'agent utilisateur

Il est bon de s'habituer à initialiser l'entête descriptif de l'agent utilisateur. Pour faire cela, utilisez User-Agent: clientname/version (contact information e.g username, email) framework/version.... Par exemple en PHP :

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');

Ne recopiez pas simplement l'agent utilisateur d'un navigateur web populaire. Cela assure que si un problème apparait réellement, il est facile de tracer son origine.

Si vous appelez l'API à partir d'un navigateur basé sur JavaScript, il est possible que vous ne puissiez pas influer sur l'entête User-Agent - cela dépend du navigateur. Pour contourner cela, utilisez l'entête Api-User-Agent .

Voir m:User-Agent_policy pour plus de détails.

Formats des données

Tous les nouveaux utilisateurs de l'API doivent utiliser JSON . Voir API:Data formats/fr pour plus de détails.

Performances

Télécharger un grand nombre de données n'est pas toujours très efficace si vous utilisez l'API Action. Sur les wikis Wikimedia, il existe des manières plus rapides pour obtenir des données en masse, voir m:Research:Data et wikitech:Portal:Data Services pour d'autres détails.

Notes

Si vos requêtes ramènent des données qui peuvent être mises en cache pour un moment, vous devrez procéder par étapes pour cela, de sorte à ne pas redemander les mêmes données plusieurs fois. Certains clients peuvent mettre en cache les données eux-mêmes, mais pour les autres (particulièrement pour les clients JavaScript), cela n'est pas possible.

C'est pourquoi, lorsque vous lisez des données à partir de l'API des services web, vous devez utiliser le plus possible les requêtes GET et non pas POST, car ces dernières ne peuvent pas être mises dans le cache et peuvent arriver sur un centre de données plus éloigné pour les configurations multi centres de données (même avec les sites Wikimedia).

Dans les cas exceptionnels où vous devez vraiment utiliser POST pour une requête de lecture, comme appeler action=parse avec une longue chaîne de wikicode, utiliser l'entête Promise-Non-Write-API-Action: true. Cela contribue à s'assurer que votre requête POST sera traitée par un serveur d'applications du centre de données le plus proche, si c'est le cas. Pour les requêtes GET, il n'est pas nécssaire de déclarer cette entête, et elle ne doit jamais être utilisée dans les requêtes inter-wiki dans une famille de wikis en utilisant CentralAuth; voir tâche T91820.

Voir aussi

• Official guidelines about API usage on Wikimedia Foundation Governance wiki
• API:Page d'accueil - Guide de démarrage rapide.
• API:Ratelimit & API:Ratelimit/Wikimedia sites

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