API:Etiquette

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Etiquette and the translation is 95% complete.
Other languages:
Deutsch • ‎Deutsch (Sie-Form)‎ • ‎English • ‎Türkçe • ‎español • ‎français • ‎italiano • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎中文 • ‎日本語

Esta página contiene las buenas prácticas que tendrías que seguir cuándo utilices el API.

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.
  • Utilizando un generador en vez de hacer una petición para 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.

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.

When you hit the request rate limit you will receive a API error response with the error code ratelimited. 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á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:

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:

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

Si estás obteniendo resultados más lentamente de lo que deseas, lee las $pautas para ayudarte a pensar en el rendimiento en general.

Si leer a través de la API en lugar de leer directamente desde bases de datos está obstaculizando el rendimiento de su cliente, considere si lo pone en el Toolforge de Wikimedia.

Véase también