API:Extensions/es

Este documento cubre la creación de un módulo API en una extensión para usar con MediaWiki 1.30 y versiones posteriores.

Creación y registro de módulo
Todos los módulos API son subclases de, pero algunos tipos de módulos usan una clase base derivada. El método de registro también depende del tipo de módulo.


 * Módulos de acción
 * Módulos que proporcionan un valor para el parámetro principal  deben subclasificar . Ellos deberían ser registrados en   utilizando la clave.


 * Módulos de formato
 * Los módulos que proporcionan un valor para el principal  parámetro tendría subclase . Ellos deberían ser registrados en   utilizando la clave  . Es muy raro para una extensión necesitar agregar un módulo de formato.


 * Submódulos de consulta
 * Módulos que proporcionan un valor para los parámetros,   o  , para   tiene subclase,  (si no se puede usar como generador) o $ ApiQueryGeneratorBase (si se puede usar como generador). Deberían ser registrados en   utilizando la clave  ,   o.

En todos los casos, el valor de la clave de registro es un objeto con el nombre de módulo (es decir, el valor del parámetro) como clave y el nombre de la clase como valor. Los módulos también pueden ser registrados condicionalmente utilizando (para módulos de acción y formato) y  (para submódulos de consulta).

Prefijo
En el constructor de tu módulo API, cuando llamas a  puedes especificar un prefijo opcional para los parámetros de tu módulo. (En la documentación generada para un módulo, este prefijo, si lo hay, aparece entre paréntesis en el encabezado del módulo). Si tu módulo es un submódulo de consulta, entonces se requiere un prefijo, desde que un cliente puede invocar múltiples submódulos, cada uno con sus propios parámetros en una sola solicitud. Para los módulos de acción y formato, el prefijo es opcional.

Parámetros
La mayoría de los módulos requieren parámetros. Estos se definen implementando. El valor de retorno es una matriz asociativa donde las claves son los nombres de parámetros (sin prefijo) y los valores son, ya sea el valor escalar por defecto para el parámetro o una matriz que define las propiedades del parámetro utilizando el  constantes definidas por.

El ejemplo ilustra la sintaxis y algunas de las más comunes constantes.

Los parámetros son documentados utilizando el mecanismo i18n de MediaWiki. Ver #Documentation para más detalles.

Ejecución y salida
El código que actualmente implementa el módulo va en el. Este código generalmente usará para obtener los parámetros de entrada, y utilizará  para obtener el objeto  para añadir cualquier salida.

Query prop submodules tendrían que utilizar para acceder al conjunto de páginas para operar.

Query submodules que pueden ser usados como generadores también necesitarán implementar que es pasado a una  que debería ser completado con las páginas generadas. En este caso, el  debería generalmente not ser usado.

Caching
Por defecto las respuestas de la API están marcadas como no almacenables en caché, ¡('Cache-Control: private')! Para los módulos de acción, puedes permitir el almacenamiento en caché llamando. Esto todavía requiere que los clientes pasen los parámetros  o   para habilitar realmente el almacenamiento en caché. Puede forzar el almacenamiento en caché llamando también.

Para los módulos de consulta, "no" llames a esos métodos. Puedes permitir el almacenamiento en caché, por el contrario implementando.

En cualquier caso, asegúrate de que la infomación privada no esté expuesta.

Manejo de token
Si tu módulo de acción cambia el wiki de alguna manera, deberías requerir un token de algún tipo. Para que esto se maneje automáticamente, implemente el método, devolviendo el token que requiere su módulo (probablemente el   Edit token). El código base API validará automáticamente el token que los clientes proporcionen en las solicitudes API de un parámetro.

Si no deseas utilizar un token que es parte del núcleo, sino más bien un token personalizado con tus propias verificaciones de permisos, usa the ApiQueryTokensRegisterTypes hook para registrar tu token.

Acceso a la base de datos maestra
Si tu módulo accede a la base de datos maestra, debería implementar el método  para devolver.

Errores de retorno
incluye varios métodos para realizar diversas comprobaciones, por ejemplo,
 * Si necesitas afirmar que se proporcionó exactamente uno de un conjunto de parámetros, usa.
 * Si necesitas afirmar que como máximo se proporcionó uno de un conjunto de parámetros, usa.
 * Si necesitas afirmar que se proporcionó al menos uno de un conjunto de parámetros, usa.
 * Si necesitas afirmar que el usuario tiene ciertos derechos, usa.
 * Si necesitas afirmar que el usuario puede realizar una acción en una página en particular, usa.
 * Si el usuario está bloqueado (y eso es importante para tu módulo), pase el objeto  a.

Pero a menudo te encontrarás con casos en los que necesitas generar un error propio. La forma habitual de hacerlo es llamar, aunque si tienes un  con la información del error, podrías pasarlo a  en su lugar.

If you need to issue a warning rather than an error, use, or if it's a deprecation warning.

Documentación
The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "query+".

Every module will need a  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

More details on API documentation are available at.

Extensions may also maintain extra API documentation on WikiMedia.org. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g. CentralAuth, MassMessage, or StructuredDiscussions). The API namespace is reserved for the API of MediaWiki core.

Extending core modules
Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:


 * APIGetAllowedParams to add or modify the module's parameter list
 * APIGetParamDescription to add or modify the module's parameter descriptions
 * APIAfterExecute to do something after the module has been executed (but before the result has been output)
 * Use APIQueryAfterExecute for,   and   modules
 * If the module is run in generator mode, APIQueryGeneratorAfterExecute will be called instead

List of extensions with API functionality
See API extensions for examples of extensions that add to or extend the API.

Probando tu extensión

 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule. La información de ayuda de tu extensión debería ser correcta.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Visit Special:ApiSandbox and interactively explore your API.
 * Visit to see additional information about your extension.