API:Etiquette/pt-br

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

Comportamento


Limite de solicitações
Não há limite rígido para as solicitações de leitura, mas pedimos que você seja atencioso para não desativar um site. A maioria dos administradores de sistema bloqueia sem cerimônia podendo colocar em risco a estabilidade do site.

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 generator 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, your user rights and the configuration of the website you are making the request to. The limits that apply to you can be determined by accessing the action=query&meta=userinfo&uiprop=ratelimits API endpoint.

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.



Análise de revisão
Embora seja possível consultar os resultados de um número de revisão específico, essa é uma operação dispendiosa para os servidores. Para recuperar uma revisão específica, use o parâmetro 'oldid', exemplo:



O parâmetro maxlag
Se a tarefa não for interativa (um usuário não aguarda um resultado), você deve usar o parâmetro maxlag. The value of the  parameter should be an integer number of seconds. For example:

Isso impedirá que sua tarefa seja executada quando a carga nos servidores for alta. Valores altos significam comportamento agressivo, valores menores são mais agradáveis.

See for more details.



Cabeçalho do Agente do Usuário
It is best practice to set a descriptive User Agent header. To do so, use. For example in PHP:

Não copie simplesmente o agente de usuário de um navegador da web (a menos que o seu cliente API seja um aplicativo JavaScript em execução no navegador web com uso do Ajax, caso em que não é possível modificar o agente de usuário). Isso garante que ao surgir um problema, será fácil rastrear o local de origem.

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.

Veja API:Identificando o cliente e m:Política do agente de usuário para mais detalhes.

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

Performance
Downloading data in bulk is not always extremely efficient using the Action API. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.

Other 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. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. 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.