API:Etiquette/fr

Cette page contient les meilleures pratiques à suivre pour utiliser l'API.

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 , au lieu de faire un nouvelle requête pour chaque titre.
 * utilisant un 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  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.

When you hit the request rate limit you will receive a with the error code. When you encounter this error, you may retry that request, however you should increase the time between subsequent requests. A common strategy for this is Exponential backoff.



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, ceci reste une opération coûteuse pour les serveurs. Pour récupérer une révision spécifique utilisez le paramètre. Par exemple :



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

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 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. Par exemple en PHP :

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  - cela dépend du navigateur. Pour contourner cela, utilisez l'entête.

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



Formats des données
Tous les nouveaux utilisateurs de l'API. Voir 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.



Autres notes
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. 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.

A cause des spécifications HTTP, les requêtes POST ne peuvent pas être mises en cache. C'est pourquoi, lorsque vous lisez des données à partir de l'API des services web, vous devez utiliser les requêtes GET et non pas POST.

Notez aussi qu'une requête ne peut pas être servie à partir du cache sauf si l'URL est exactement la même. If you make a request for, and cache the result, then a request for   will not go through the cache — even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.



Voir aussi

 * - Guide de démarrage rapide.