API:Extensiones

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 $hook1 (para módulos de acción y formato) y $hook2 (para submódulos de consulta). Modules may also be registered conditionally using the ApiMain::moduleManager (for action and format modules) and ApiQuery::moduleManager (for query submodules) hooks.

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. For action and format modules, the prefix is optional.

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. These are defined by implementing getAllowedParams(). The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_* constants defined by 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. Este código generalmente usará $this→extractRequestParams() para obtener los parámetros de entrada y usará $this→getResult() para obtener el objeto ApiResult al que se agregar cualquier salida.

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 generalmente "no" debe usarse.

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().

Para los módulos de consulta, no llames a esos métodos. Puedes permitir el almacenamiento en caché, por el contrario implementando 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 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,

• Si necesitas afirmar que se proporcionó exactamente uno de un conjunto de parámetros, use $this→requireOnlyOneParameter().

• Si necesitas afirmar que se suministró como máximo uno de un conjunto de parámetros, usa $this→requireMaxOneParameter().

• Si necesitas afirmar que se suministró al menos uno de un conjunto de parámetros, usa $this→requireAtLeastOneParameter()

• Si necesitas afirmar que el usuario tiene ciertos derechos, usa $this→checkUserRightsAny().

• Si necesitas afirmar que el usuario puede realizar una acción en una página en particular, usa $this→checkTitleUserPermissions().

• Si el usuario está bloqueado (y eso es importante para su módulo), pasa el objeto Block a $this→dieBlocked().

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.

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+". 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+.

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.

Más detalles sobre la documentación de la API están disponibles en API:Localizació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.

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
• APIGetParamDescriptionMessages - para agregar o modificar las descripciones de los parámetros del módulo
• APIAfterExecute - para hacer algo después de que se haya ejecutado el módulo (pero antes de que se haya generado el resultado)
  • Usa APIQueryAfterExecute para los módulos prop=, list= y meta=
    • Si el módulo se ejecuta en modo generador, se llamará en su lugar APIQueryGeneratorAfterExecute

Lista de extensiones con funcionalidad API

Consulte Categoría:Extensiones de API 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.
  • Omitir y exprimir parámetros de URL en la cadena de consulta, verifique la respuesta de su extensión.
• Visita Special:ApiSandbox y explora interactivamente tu API.

• Visita $api para ver información adicional sobre tu extensión.

api.php?action=paraminfo&modules=myext [Prueba en ApiSandbox]