API:Etiquette

Esta página contiene las buenas prácticas que tendrías que seguir cuándo utilices el API. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.

Comportamiento

Límite de petición

No hay un límite estricto y rápido para las solicitudes de lectura, pero sea considerado e intente no eliminar un sitio. La mayoría de los administradores de sistemas se reservan el derecho de bloquearlo sin ceremonias si pones en peligro la estabilidad de su sitio.

Haciendo tus solicitudes en serie en lugar de en paralelo, esperando a que finalice una solicitud antes de enviar una nueva solicitud, debería resultar en una tasa de solicitud segura. También es recomendado que solicites varios artículos en una sola solicitud:

• Usar el carácter de canalización (|) siempre que sea posible, por ejemplo titles=PageA|PageB|PageC, en lugar de hacer una nueva solicitud para cada título.
• Usar un generator en lugar de hacer una petición por cada resultado de otra petición.

• Use la compresión GZip al realizar llamadas API configurando Accept-Encoding: gzip para reducir el uso de ancho de banda.

Las solicitudes que realizan en ediciones, modifican el estado o de otro modo no son solicitudes de solo lectura, están sujetas a limitación de velocidad. El límite de tarifa exacto que se aplica puede depender del tipo de acción, sus derechos de usuario y la configuración del sitio web al que realiza la solicitud. Los límites que se te aplican a ti se pueden determinar accediendo al punto final de la API de action=query&meta=userinfo&uiprop=ratelimits.

api.php?action=query&format=json&meta=userinfo&uiprop=ratelimits [Prueba en ApiSandbox]

Cuando alcances el límite de tasa de solicitud, recibirás un API error response con el código de error ratelimited. Cuando encuentres este error, puedes volver a intentar esa solicitud, sin embargo, debe aumentar el tiempo entre solicitudes posteriores. Una estrategia común para esto es Retroceso exponencial.

Análisis de revisiones

Si bien es posible consultar los resultados de un número de revisión específico utilizando el parámetro revid, esta es una operación costosa para los servidores. Para recuperar una revisión específica, use el parámetro oldid. Por ejemplo:

api.php?action=parse&format=json&prop=images&oldid=254862759 [Prueba en ApiSandbox]

El parámetro maxlag

Si tu tarea no es interactiva, es decir, un usuario no está esperando el resultado, debes usar el parámetro maxlag. El valor del parámetro maxlag debe ser un número entero de segundos. Por ejemplo:

api.php?action=query&format=json&titles=Main%20Page&maxlag=1 [Prueba en ApiSandbox]

Esto evitará que su tarea se ejecute cuando la carga en los servidores sea alta. Los valores más altos significan comportamiento más agresivo, los valores más bajos son mejores.

Ver Manual:Parámetro maxlag para más detalles.

El encabezado User-Agent

Se recomienda establecer un encabezado de agente de usuario descriptivo. Para hacerlo, usa User-Agent:nombre de cliente/versión (información de contacto, por ejemplo nombre de usuario, correo electrónico) framework/version.... Por ejemplo en PHP:

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

No simplemente copies el agente-de-usuario de un navegador web popular. Esto garantiza que si surge un problema, es fácil rastrear dónde se origina.

Si estás llamando a la API desde JavaScript basado en el navegador, es posible que no puedas influir en el encabezado de User-Agent, dependiendo del navegador. Para evitar esto, usa el encabezamiento Api-User-Agent.

Consulta m:User-Agent_policy para más detalles.

Formatos de dato

Todos los nuevos usuarios de API deben usar JSON . Ver API:Formatos de dato para más detalles.

Rendimiento

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.

Whenever you're reading data from the web service API, you should try to use GET requests if possible, not POST, as the latter are not cacheable and, in multi-datacenter configurations (including Wikimedia sites), may go to a farther data center.

In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header. This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate. There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see task T91820.

Véase también

• Official guidelines about API usage on Wikimedia Foundation Governance wiki
• API:Portada - La guía de inicio rápida.
• API:Ratelimit & API:Ratelimit/Wikimedia sites

• Maintained by MediaWiki Interfaces Team.
• Live chat (IRC): #mediawiki-core ^connect
• Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)