API:Etiquette/it

This page contains the best practices that should be followed when using the API.

Limiti di richieste
Non c'è un limite fisso sulle richieste in lettura, ma ti chiediamo di essere così gentile da non tentare di interrompere il servizio di un sito. Molti amministratori di sistema si riservano il diritto di bloccarti senza tanti complimenti se metti a repentaglio la stabilità del loro sito.

Making your requests in series rather than in parallel, by waiting for one request to finish before sending a new request, should result in a safe request rate. It is also recommended that you ask for multiple items in one request by:


 * Using the pipe character whenever possible e.g , instead of making a new request for each title.
 * Using a instead of making a request for each result from another request.


 * Use GZip compression when making API calls by setting  to reduce bandwidth usage.

Requests which make edits, modify state or otherwise are not read-only requests, are subject to rate limiting. The exact rate limit being applied might depend on the type of action and your user rights.

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.

Analizzare le revisioni
Sebbene sia possibile ottenere dei risultati da uno specifico numero di revisione, questa è un'operazione dispensiva per i server. Per ottenere una specifica revisione usa il parametro 'oldid', ad esempio:

Utilizzo del parametro maxlag
Se il tuo compito non richiede interazione (ad esempio se l'utente non attende per il risultato) dovresti utilizzare il parametro maxlag. The value of the  parameter should be an integer number of seconds. For example:

Questo preverrà che il tuo lavoro continui a rimanere in esecuzione mentre il carico sui server è alto. Un valore alto significa un comportamento più aggressivo, un valore basso è più apprezzato.

See for more details.

User-Agent header
It is best practice to set a descriptive User Agent header. To do so, use. For example in PHP:

Non copiare semplicemente l'user-agent di un browser web popolare (a meno che il tuo client delle API non sia un'applicazione JavaScript eseguita dal suddetto browser web tramite Ajax, in questo caso uno non può modificare l'user-agent.) Questo fa sì che laddove emerga un problema sia facile tracciare da dove provenga.

If you are calling the API from browser-based JavaScript, you may not be able to influence the  header, depending on the browser. To work around this, use the  header.

Vedi API:Main page/it#Identificare il tuo client e m:User-Agent policy per dettagli.

Data formats
All new API users. See for more details.

Performance
Se stai cercando di scoprire come mai stai ottenendo risultati in modo più lento rispetto a come vorresti, prova per pensare alle performance in generale.

Se stai scoprendo che la lettura tramite API piuttosto che tramite lettura diretta ai database sta impedendo le performance del tuo client, considera se sia il caso di inserire il tuo tool in Wikimedia Toolforge.