API:Vorlagenparameter

Mit Stand MediaWiki 1.32 können API-Anrufe zwei Level-Arrays nutzen, um Daten an die API zu übergeben. Dadurch werden die für API-Server verfügbaren Datenformate zum Erhalt von Argumenten von API-Clients erweitert.

Überblick

Die API-Struktur erlaubt API-Anrufen, zwei Stufen von Argumenten zur Auswertung an eine API zu übergeben.

• Ein Modul kann einen Vorlagenparameter wie "{frucht}-menge" definieren, wobei die erkannten Parameter den Werten eines Parameters mit mehreren Werten entsprechen. Clients können dann Abfragen wie "fruits=apples|bananas&apples-quantity=1&bananas-quantity=5" stellen.
• action=paraminfo wird Vorlagenparameter-Definitionen getrennt von normalen Parametern ausgeben. Alle Parameter-Definitionen enthalten nun einen "Index"-Schlüssel, um es Clients zu ermöglichen, eine Parameter-Sortierung zu pflegen, wenn normale und Vorlagenparameter vermischt werden.

Früchte	Menge
Äpfel	1
Bananen	5

Client-API

Der Client kann Vorlagenparameter genau so verwenden, wie ein Webservice aufgerufen wird, wobei Abfrage-Zeichenketten-Argumente oder HTTP-POST-Argumente genutzt werden.

Parameterinformationen

Die "paraminfo"-API-Abfrage kann genutzt werden, um die API über die Struktur ihrer Parameter abzufragen.

In diesem Beispiel heißt die Erweiterung ParameterTemplateDemo.

Für eine Beispiel-Entwicklungsmaschine (Wiki befindet sich unter machine/wikiprefix) wäre die API-Test-URL: http://machine/wikiprefix/api.php?action=paraminfo&modules=ParameterTemplateDemo

was folgendes ergeben würde:

{
    "paraminfo": {
        "helpformat": "none",
        "modules": [
            {
                "name": "ParameterTemplateDemo",
                "classname": "ParameterTemplateDemoAPI",
                "path": "ParameterTemplateDemo",
                "group": "action",
                "prefix": "",
                "source": "ParameterTemplateDemo",
                "sourcename": "ParameterTemplateDemo",
                "readrights": "",
                "helpurls": [],
                "parameters": [
                    {
                        "index": 1,
                        "name": "fruits",
                        "required": "",
                        "multi": "",
                        "lowlimit": 50,
                        "highlimit": 500,
                        "limit": 500,
                        "type": "string"
                    }
                ],
                "templatedparameters": [
                    {
                        "index": 2,
                        "name": "{f}-quantity",
                        "templatevars": {
                            "f": "fruits"
                        },
                        "multi": "",
                        "lowlimit": 50,
                        "highlimit": 500,
                        "limit": 500,
                        "type": "integer"
                    }
                ]
            }
        ]
    }
}

Server-API-Implementation

Dieser Abschnitt soll Entwicklern von Erweiterungen helfen, die als Teil ihrer Erweiterung neue APIs einführen möchten.

Hinzufügen von Erweiterungen

Wie bei allen Erweiterungen muss ein einzigartiges Verzeichnis zum Verzeichnis der MediaWiki-Erweiterung hinzugefügt werden. In diesem Beispiel heißt die Erweiterung "MyExample".

LocalSettings.php muss einen Verweis auf die neue Erweiterung enthalten, wie:

wfLoadExtension( 'MyExample' );

Die JSON-Datei der Erweiterung hat den Namen extension.json im Haupt-Verzeichnis des Ordners der Erweiterung (in diesem Fall /extensions/ParameterTemplatesDemo/extension.json) und enthält den Namen, Version, Beschreibung, APIModule und Einträge zu AutoloadKlassen. Die Verweise auf Spezialseiten und Ressourcen-Module dienen für clientseitige Abfragen.

{
	"name": "MyExample",
	"version": 1,
	"description": "Example that demonstrates API parameterized templates (both client and server)",
	"type": "other",

	"@APIModules": "Key is the API module name (lowercase, used for the api.php action parameter). Value is the PHP class that implements it.",
	"APIModules": {
		"parameterdemo": "MediaWiki\\Extension\\MyExample\\ApiParameterDemo"
	},
	"MessagesDirs": {
		"MyExample": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.MyExample": {
			"packageFiles": [
				"modules/ext.MyExample/demo.js"
			],
			"dependencies": [
				"mediawiki.api",
				"mediawiki.util"
			]
		}
	},
	"AutoloadNamespaces": {
		"MediaWiki\\Extension\\MyExample\\" : "includes/"
	},
	"manifest_version": 1
}

I18N

Die Server-Implementation verlässt sich auf ein gültiges i18n-Verzeichnis und eine existierende JSON-Datei, die jedoch in diesem Beispiel noch nicht genutzt werden.

Implementierungsklasse

Die Implementierungsklasse muss sich im eingeschlossenen Verzeichnis befinden. Die Implementierungsklasse muss die Benutzeroberfläche von ApiBase.php implementieren.

<?php

namespace MediaWiki\Extension\MyExample;

class ApiParameterTemplateDemo  extends ApiBase {

    public function getAllowedParams() {
        return array(
            'fruits' => array (
                ApiBase::PARAM_TYPE => 'string',
                ApiBase::PARAM_REQUIRED => true,
                ApiBase::PARAM_ISMULTI => true,
            ),
            '{f}-quantity'=> array(
                ApiBase::PARAM_TYPE => 'integer',
                ApiBase::PARAM_ISMULTI => true,
                // a reference to prior parameter
                ApiBase::PARAM_TEMPLATE_VARS => [ 'f' => 'fruits'],
            )
        );
    }

    public function execute() {
        $result = $this->getResult();

        $requestValues = $this->getRequest()->getQueryValues();
        $fruits = explode('|', $this->getRequest()->getVal('fruits'));
        
        // wfDebug( __METHOD__ . ': fruits = ' . json_encode( $fruits ) );
        
        foreach ($fruits as $fruit) {
            $quantity = $this->getRequest()->getVal($fruit . '-quantity');
            // wfDebug( "$fruit is $quantity" );
            $result->addValue( null, $fruit, $quantity );
        }
     }
}

Diese Klasse kann getestet werden, indem das integrierte API-Test-Modul genutzt wird. Die URL wäre http://machine/wikiprefix/api.php?action=ParameterTemplateDemo&fruits=apples%7Cbananas&apples-quantity=1&bananas-quantity=5

Im Prinzip ein "Hallo Welt", diese Antwort gibt nur das zurück, was mit der Abfrage-Zeichenkette übergeben wurde:

{
    "apples": "1",
    "bananas": "5"
}