API:Extensiones

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Extensions and the translation is 58% complete.
Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎polski • ‎português • ‎русский • ‎العربية • ‎中文 • ‎日本語 • ‎한국어

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 ApiBase , 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 action deben subclasificar ApiBase . Ellos deberían ser registrados en extension.json utilizando la clave APIModules.
Módulos de formato
Los módulos que proporcionan un valor para el principal format parámetro tendría subclase ApiFormatBase. Ellos deberían ser registrados en extension.json utilizando la clave APIFormatModules. 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 prop, list o meta, para action=query tiene subclase, ApiQueryBase (si no se puede usar como generador) o ApiQueryGeneratorBase (si se puede usar como generador). Deberían ser registrados en extension.json utilizando la clave APIPropModules, APIListModules o APIMetaModules.

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 ApiMain::moduleManager (para módulos de acción y formato) y ApiQuery::moduleManager (para submódulos de consulta).

Implementación

Prefijo

En el constructor de tu módulo API, cuando llamas a parent::__construct() 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 getAllowedParams(). 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 PARAM_* constantes definidas por ApiBase.

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

    protected function getAllowedParams() {
        return [
            // Un parámetro opcional con un valor por defecto
            'simple' => 'value',

            // Un parámetro requerido
            'required' => [
                ApiBase::PARAM_TYPE => 'string',
                ApiBase::PARAM_REQUIRED => true,
            ],

            // Un parámetro que acepta múltiples valores de una lista
            'variable' => [
                // El conjunto de valores por defecto
                ApiBase::PARAM_DFLT => 'foo|bar|baz',
                // Todo valores posibles
                ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
                // Indica que se aceptan múltiples valores
                ApiBase::PARAM_ISMULTI => true,
                // Utilice mensajes de documentación estándar "por valor"
                ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
            ],

            // Un parámetro "límite" estándar. Generalmente, es mejor no variar de este estándar.
            'limit' => [
                ApiBase::PARAM_DFLT => 10,
                ApiBase::PARAM_TYPE => 'limit',
                ApiBase::PARAM_MIN => 1,
                ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
                ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
            ],
        ];
    }

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 execute() método. This code will generally use $this->extractRequestParameters() to get the input parameters, and will use $this->getResult() to get the ApiResult object to add any output to.

Query prop submodules tendrían que utilizar $this->getPageSet() para acceder al conjunto de páginas para operar.

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

In this case, the ApiResult should generally not be used.

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 $this->getMain()-> setCacheMode(). Esto todavía requiere que los clientes pasen los parámetros maxage o smaxage para habilitar realmente el almacenamiento en caché. Puede forzar el almacenamiento en caché llamando también $this->getMain()-> setCacheMaxAge().

This still requires clients pass the maxage or smaxage parameters to actually enable caching. You can force caching by also calling $this->getMain()->setCacheMaxAge().

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

You can allow caching by instead implementing getCacheMode().

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 needsToken(), devolviendo el token que requiere su módulo (probablemente el 'csrf' Edit token).

El código base API validará automáticamente el token que los clientes proporcionen en las solicitudes API de un parámetro token.

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 isWriteMode() para devolver true.

Errores de retorno

ApiBase incluye varios métodos para realizar diversas comprobaciones, por ejemplo,

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

The usual way to do that is to call $this->dieWithError(), although if you have a StatusValue with the error information you could pass it to $this->dieStatus() instead.

Si necesitas emitir una advertencia en lugar de un error, usa $this-> addWarning (), o $this-> addDeprecation() si es una advertencia de desaprobación.

Documentación

La API se documentó utilizando el mecanismo i18n de MediaWiki. Los mensajes necesitados generalmente tienen nombres predeterminados basados ​​en la "ruta" del módulo. Para los módulos de acción y formato, la ruta es la misma que el nombre del módulo utilizado durante el registro. Para submódulos de consulta, es el nombre con el prefijo "query+".

Cada módulo necesitará un mensaje apihelp-"$path"- summary, que debe ser una descripción de una línea del módulo. Si se necesita texto de ayuda adicional, también se puede crear apihelp-"$path"-extended-description . Cada parámetro necesitará un mensaje apihelp- "$path"-param-"$name", y los parámetros que usan PARAM_HELP_MSG_PER_VALUE también necesitarán un apihelp-"$path"-paramvalue-"$name"-"$value" para cada valor.

If additional help text is needed, apihelp-$path-extended-description may be created as well. Each parameter will need a apihelp-$path-param-$name message, and parameters using PARAM_HELP_MSG_PER_VALUE will also need a apihelp-$path-paramvalue-$name-$value for each value.

Más detalles sobre la documentación de la API están disponibles en API:Regionalización .

Las extensiones también pueden mantener documentación API adicional en WikiMedia.org. Esto debe ubicarse en la página principal de la extensión o, si se requiere más espacio, en páginas llamadas Extension:<ExtensionName>/ API o subpáginas de las mismas (p. Ej. CentralAuth, MassMessage o StructuredDiscussions). El espacio de nombres de la API está reservado para la API del núcleo de MediaWiki.

This should be located on the extension's main page or, if more space is required, on pages named Extension:<ExtensionName>/API or subpages thereof (e.g. CentralAuth , MassMessage , or StructuredDiscussions ). The API namespace is reserved for the API of MediaWiki core.

Módulos principales extendidos

Desde MediaWiki 1.14, es posible extender la funcionalidad de los módulos del núcleo utilizando los siguientes ganchos:

APIGetAllowedParams para agregar o modificar la lista de parámetros del módulo

Lista de extensiones con funcionalidad API

Consulte API extensions para ver ejemplos de extensiones que agregan o extienden la API.

Probando tu extensión

  • Visita api.php y navegue a la ayuda generada para su módulo o submódulo de consulta.

La información de ayuda de tu extensión debería ser correcta.

    • Las URL de ejemplo que proporcionó en getExamplesMessages() deberían aparecer en "Ejemplos", intente hacer clic en ellas.