API:Tutorial

Diese Seite ist Teil der Dokumentation der MediaWiki action API.

In diesem Tutorial lernst du die MediaWiki Action API kennen, wie du sie benutzt, das Anfragen-Format, eine einfache Abfrage und Beispiele von Projekten, welche die Action API verwenden.

Durchsuche Toolforge nach Demo-Apps

Übersicht über die MediaWiki Action API

Die MediaWiki Action API ist ein REST-Webservice, der es Benutzern ermöglicht, bestimmte Wiki-Aktivitäten wie Seitenerstellung, Authentifizierung, Parsing, Suchen, etc. auszuführen. API:Main page ist ein guter Ausgangspunkt, um die API zu verstehen.

Dein Programm sendet Abfragen an die API, um Zugriff auf Wiki-Funktionen zu erhalten. Zum Beispiel bei einem Wiki anmelden, eine Seite erstellen und bearbeiten, nach einem Titel suchen, nach Inhalt suchen oder Inhalt parsen. Die Action API ist für dritte Entwickler, Entwickler von Wikimedia-Erweiterungen und Administratoren von Wiki-Seiten verfügbar.

Auf der rechten Seitenleiste dieser Seite befinden sich viele Funktionen, die von der API unterstützt werden, nach Kategorien zusammengefasst. Bevor du Abfragen an einen Wiki-Server sendest, lese zunächst die Übersichtsseiten wie Datenformate, Fehler und Warnungen und die Action API FAQ.

Wie die MediaWiki Action API verwendet wird

Du kannst clientseitig über HTTP Daten vom Server anfordern und die Antwort in einem Standardformat erhalten (typischerweise JSON). Eine Abfrage besteht aus einem Endpunkt und einer Reihe von Parametern. Es können zwei Abfragetypen gestellt werden: GET und POST. Bei einer GET-Abfrage würde ein Parameter eine Abfrage-Zeichenkette in der URL enthalten. Für eine POST-Abfrage formatiere die Parameter im Format JSON.

Anfragen-Format

Alle Wikimedia-Wikis haben Endpunkte im Format http://example.org/w/api.php. Nutze den entsprechenden Endpunkt, um auf der Hauptseite von MediaWiki oder der englischsprachigen Wikipedia zu agieren. Zum Beispiel findet sich die englischsprachige Wikipedia auf https://en.wikipedia.org/w/api.php. Nutze den Test-Wiki-Endpunkt https://test.wikipedia.org/w/api.php, um neue Konten oder das Bearbeiten von Seiten zu testen.

Füge den Parameter action zur Abfrage-Zeichenkette in der URL hinzu. Er sagt der API, welche Aktion sie ausführen soll. Die bekannteste Aktion ist query (die URL würde action=query) enthalten, was es ermöglicht, Daten aus einem Wiki zu erhalten. Gib nach dem Parameter action einen anderen Parameter an, um anzugeben, welchen der drei Abfragemodul-Typen nutzen möchtest:

prop - Eigenschaften von Seiten erhalten
list - Liste von Seiten erhalten, die ein bestimmtes Kriterium erfüllen
meta - Metainformationen über das Wiki und seine Benutzer erhalten

Schließe dann noch den Parameter format ein, der der API sagt, in welchem Format die Ergebnisse erhalten werden sollen. Das empfohlene Format ist JSON. Die API hat in der Vergangenheit andere Ausgabeformate unterstützt, die jedoch nicht allgemein empfohlen werden.

Eine einfache Abfrage

Lass uns eine einfache Abfrage als Beispiel nehmen, um zu verstehen, wie eine typische GET-Abfrage und die Antwort im Kontext der Action API aussehen würden.

Lass uns nach einem Titel in einem Wiki suchen. Wir werden das auf API:Suche dokumentierte Modul search nutzen.

GET-Anfrage

Um nach einem Seitentitel oder Inhalt, der mit Craig Noone übereinstimmt, zu suchen, würde die URL für die HTTP-GET-Abfrage so aussehen:

api.php?action=query&list=search&srsearch=Craig%20Noone&format=json [In der ApiSandbox ausprobieren]

Explanation of each part of the URL:

http://en.wikipedia.org/w/api.php is the main endpoint. In this case it is English Wikipedia.
action=query means fetch data from wiki.
list=search means get list of pages matching a criteria.
srsearch=Craig%20Noone indicates the page title or content to search for. The %20 indicates a space character in a URL.

format=json indicates JSON output, which is the recommended output format.

Antwort

The response is a JSON format document with a list of pages titles that match Craig Noone :

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}

Examples of projects using Action API

Some example of projects in Wikimedia that use Action API:

Wikipedia iOS App, in which one of the features is to search for wiki pages near your location.

Bots that operate on a wiki. Pywikibot is a bot framework written in Python that interfaces with MediaWiki API which a lot of bot developers use.

API use in visualizing data obtained from a wiki. Such as this neat visualization that shows real time edits made on Wikipedia.

Zusätzliche Anmerkungen

Several sites are using MediaWiki. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
If you want to make a lot of API calls, and perhaps run very busy and active bots, talk to wiki admins ahead of time, so they do not block you. See list of Administrators of Wikimedia projects. Read more about this topic on API:Etikette .

All data modifying actions such as logging, editing or moving a page, and watching or patrolling changes would require tokens. You would need to obtain tokens via API:Tokens to proceed further.

Ressourcen

Use Special:APISandbox to experiment with the Action API. You can play around with supported actions, specify a value for parameters, and send requests to the API to see the results on the same page.
Wikimedia dumps so you can work with them locally.
Read through tutorials: An Introduction to API's and What is REST — A Simple Explanation for Beginners.
MediaWiki API help provides auto-generated API documentation of all supported modules.
API:Main page bietet einen Überblick der Action API.
Introduction to the MediaWiki API by User:Roan_Kattouw_(WMF) at the San Francisco Hackathon, 2012. This tutorial guide goes along with the video.
GitHub: MediaWiki API Demos