Pomocník API MediaWiki

Toto je automaticky generovaná dokumentačná stránka MediaWiki Action API.

Všeobecné informácie

Stav: API MediaWiki je vyspelé a stabilné rozhranie, ktoré je aktívne podporované a vylepšované. Hoci sa tomu snažíme vyhýbať, občas môžeme potrebovať vykonať nekompatibilné zmeny; prihláste sa na odber emailovej konferencie mediawiki-api-announce, aby ste boli informovaní o aktualizáciách.

Chybné požiadavky: Keď sa do API pošlú chybné požiadavky, pošle sa HTTP hlavička s kľúčom „MediaWiki-API-Error“ a hodnota hlavičky aj vrátený chybový kód budú nastavené na rovnakú hodnotu. Ďalšie informácie nájdete na API: Chyby a upozornenia.

Metódy požiadaviek

Požiadavky Action API môžu používať metódy GET a POST. Uprednostňujte metódu GET, ktorá umožňuje smerovať požiadavky na rýchlejšie replikačné servery a ukladať odpovede do vyrovnávacej pamäte, pokiaľ by dĺžka URL s parametrami neprekročila jej limit (bežne 8000 bajtov) alebo modul neprijíma iba požiadavky POST.

Parametre požiadaviek POST sa môžu posielať v dotazovej časti URL požiadavky (ako pri požiadavkách GET) aj v tele požiadavky POST a miešanie oboch spôsobov v jednej požiadavke je povolené. Určité parametre, ako napríklad heslá, sa musia posielať v tele požiadavky. Ak sa rovnaký parameter pošle ako súčasť URL aj v tele požiadavky, musí mať na oboch miestach rovnakú hodnotu.

Dátové typy

Vstup do MediaWiki by mal byť NFC-normalizované UTF-8. MediaWiki sa môže pokúsiť konvertovať iný vstup, ale môže to spôsobiť zlyhanie niektorých operácií (napríklad úprav s kontrolami MD5).

Parametre, ktoré prijímajú viacero hodnôt, sa bežne posielajú s hodnotami oddelenými znakom zvislej čiary, napr. param=value1|value2 alebo param=value1%7Cvalue2. Ak hodnota musí obsahovať znak zvislej čiary, použite ako oddeľovač U+001F (Unit Separator) a pred hodnotu vložte U+001F, napr. param=%1Fvalue1%1Fvalue2.

Niektoré typy parametrov v požiadavkách API vyžadujú ďalšie vysvetlenie:

boolean

Logické (boolean) parametre fungujú ako HTML zaškrtávacie polia: ak je parameter zadaný, bez ohľadu na hodnotu sa považuje za pravdivý (true). Pre hodnotu nepravda (false) parameter úplne vynechajte.

expiry

Hodnoty vypršania môžu byť relatívne (napr. 5 months alebo 2 weeks) alebo absolútne (napr. 2014-09-18T12:34:56Z). Ak vypršanie nemá nastať, použite infinite, indefinite, infinity alebo never.

timestamp

Časové pečiatky možno zadať v niekoľkých formátoch, podrobnosti nájdete vo vstupných formátoch knižnice Timestamp zdokumentovaných na mediawiki.org. Odporúča sa dátum a čas podľa ISO 8601: 2001-01-15T14:56:00Z. Na zadanie aktuálneho času možno použiť reťazec now.

Limity

Väčšina modulov API môže prijať až 50 vstupov v parametroch s viacerými hodnotami a môže vrátiť až 500 výsledkov na jeden dotaz (50 výsledkov pre pomalé dotazy).

Pre používateľov s právom apihighlimits (Boti a Správcovia) sa limity zvyšujú na 500 vstupov a 5 000 výsledkov (500 výsledkov pre pomalé dotazy).

Šablónové parametre

Šablónové parametre podporujú prípady, keď modul API potrebuje hodnotu pre každú hodnotu nejakého iného parametra. Ak by napríklad existoval modul API na vyžiadanie ovocia, mohol by mať parameter fruits na určenie, ktoré ovocie sa žiada, a šablónový parameter {fruit}-quantity na určenie, koľko kusov každého ovocia sa žiada. Klient API, ktorý chce 1 jablko, 5 banánov a 20 jahôd, by potom mohol vytvoriť požiadavku ako fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20.

Hlavný modul

Specify the action to perform, the format of the response, and options that apply to all API modules.

Konkrétne parametre:
action

Ktorá akcia sa má vykonať. Tento parameter by sa mal posielať ako súčasť URL požiadavky (nie tela POST), aby sa uľahčilo ladenie, analytika a smerovanie alebo filtrovanie požiadaviek.

acquiretempusername
Získať meno dočasného používateľa a uložiť ho do aktuálnej relácie, ak je povolené vytváranie dočasných účtov a aktuálny používateľ je odhlásený. Ak už bolo nejaké meno uložené, vráti to isté meno.
block
Zablokovať používateľa.
changeauthenticationdata
Zmeniť autentifikačné údaje aktuálneho používateľa.
changecontentmodel
Zmeniť model obsahu stránky
checktoken
Skontrolovať platnosť tokenu z action=query&meta=tokens.
clearhasmsg
Vymaže príznak hasmsg pre aktuálneho používateľa.
clientlogin
Prihlásiť sa na wiki pomocou interaktívneho postupu.
compare
Získať rozdiel medzi dvoma stránkami.
createaccount
Vytvoriť nový používateľský účet.
delete
Vymazať stránku.
edit
Vytvárať a upravovať stránky.
emailuser
Poslať email používateľovi.
embedvideo
Get generated video embed code for given parameters.
expandtemplates
Expanduje všetky šablóny vo wikitexte.
feedcontributions
Vráti kanál príspevkov používateľa.
feedrecentchanges
Vráti kanál posledných zmien.
feedwatchlist
Vráti kanál zoznamu sledovaných.
filerevert
Vrátiť súbor na starú verziu.
googleplusprofileinfo
Makes a request to the Google+ api to find out some personal information about a given user.
help
Zobraziť pomocníka pre zadané moduly.
imagerotate
Otočiť jeden alebo viac obrázkov.
import
Importovať stránku z inej wiki alebo z XML súboru.
jsonconfig
Allows direct access to JsonConfig subsystem.
languagesearch
Vyhľadávať názvy jazykov v akomkoľvek písme.
linkaccount
Prepojiť účet od poskytovateľa tretej strany s aktuálnym používateľom.
login
Prihlásiť sa a získať autentifikačné cookies.
logout
Odhlásiť sa a vymazať údaje relácie.
managetags
Vykonávať úlohy správy súvisiace so značkami zmien.
mergehistory
Zlúčiť históriu stránok.
move
Presunúť stránku.
opensearch
Vyhľadávať na wiki pomocou protokolu OpenSearch.
options
Zmeniť nastavenia aktuálneho používateľa.
paraminfo
Získať informácie o moduloch API.
parse
Parsuje obsah a vráti výstup parsera.
patrol
Strážiť stránku alebo revíziu.
protect
Zmeniť úroveň ochrany stránky.
purge
Vyprázdniť vyrovnávaciu pamäť pre zadané názvy stránok.
query
Získavať dáta z MediaWiki a o MediaWiki.
removeauthenticationdata
Odstrániť autentifikačné údaje aktuálneho používateľa.
resetpassword
Poslať používateľovi email na obnovenie hesla.
revisiondelete
Vymazávať a obnovovať revízie.
rollback
Vrátiť poslednú úpravu stránky.
rsd
Exportovať schému RSD (Really Simple Discovery).
setnotificationtimestamp
Aktualizovať časovú pečiatku upozornení pre sledované stránky.
setpagelanguage
Zmeniť jazyk stránky.
tag
Pridávať alebo odstraňovať značky zmien z jednotlivých revízií alebo položiek záznamov.
unblock
Odblokovať používateľa.
undelete
Obnoviť revízie vymazanej stránky.
unlinkaccount
Odstrániť prepojený účet tretej strany od aktuálneho používateľa.
upload
Nahrať súbor alebo získať stav čakajúcich nahraní.
userrights
Zmeniť členstvo používateľa v skupinách.
validatepassword
Overiť heslo voči politikám hesiel wiki.
watch
Pridávať alebo odstraňovať stránky zo zoznamu sledovaných aktuálneho používateľa.
cspreport
Interné. Používajú prehliadače na hlásenie porušení pravidiel Content Security Policy. Tento modul by sa nemal nikdy používať, s výnimkou automatického použitia webovým prehliadačom kompatibilným s CSP.
editcheckreferenceurl
Interné. Check the status of a URL for use as a reference.
sanitize-mapdata
Interné. Performs data validation for Kartographer extension
stashedit
Interné. Pripraviť úpravu v zdieľanej vyrovnávacej pamäti.
visualeditor
Interné. Returns HTML5 for a page from the Parsoid service.
visualeditoredit
Interné. Save an HTML5 page to MediaWiki (converted to wikitext via the Parsoid service).
Jedna z nasledujúcich hodnôt: acquiretempusername, block, changeauthenticationdata, changecontentmodel, checktoken, clearhasmsg, clientlogin, compare, createaccount, delete, edit, emailuser, embedvideo, expandtemplates, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, googleplusprofileinfo, help, imagerotate, import, jsonconfig, languagesearch, linkaccount, login, logout, managetags, mergehistory, move, opensearch, options, paraminfo, parse, patrol, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setnotificationtimestamp, setpagelanguage, tag, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, watch, cspreport, editcheckreferenceurl, sanitize-mapdata, stashedit, visualeditor, visualeditoredit
Predvolené: help
format

Formát výstupu.

json
Vypísať dáta vo formáte JSON.
jsonfm
Vypísať dáta vo formáte JSON (pekne naformátované v HTML).
none
Nevypísať nič.
php
Vypísať dáta v serializovanom formáte PHP.
phpfm
Vypísať dáta v serializovanom formáte PHP (pekne naformátované v HTML).
rawfm
Vypísať dáta vrátane ladiacich prvkov vo formáte JSON (pekne naformátované v HTML).
xml
Vypísať dáta vo formáte XML.
xmlfm
Vypísať dáta vo formáte XML (pekne naformátované v HTML).
Jedna z nasledujúcich hodnôt: json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm
Predvolené: jsonfm
maxlag

Maximálne oneskorenie (maxlag) možno použiť, keď je MediaWiki nainštalovaná na klastri s replikovanou databázou. Aby akcie nespôsobovali ďalšie replikačné oneskorenie, tento parameter môže prinútiť klienta čakať, kým replikačné oneskorenie neklesne pod zadanú hodnotu. V prípade nadmerného oneskorenia sa vráti chybový kód maxlag so správou ako Waiting for $host: $lag seconds lagged.
Ďalšie informácie nájdete na stránke Manuál: parameter maxlag.

Typ: celé číslo
smaxage

Nastaviť HTTP hlavičku riadenia vyrovnávacej pamäte s-maxage na tento počet sekúnd. Chyby sa nikdy neukladajú do vyrovnávacej pamäte.

Typ: celé číslo
Hodnota nesmie byť menšia ako 0.
Predvolené: 0
maxage

Nastaviť HTTP hlavičku riadenia vyrovnávacej pamäte max-age na tento počet sekúnd. Chyby sa nikdy neukladajú do vyrovnávacej pamäte.

Typ: celé číslo
Hodnota nesmie byť menšia ako 0.
Predvolené: 0
assert

Overiť, že používateľ je prihlásený (prípadne aj ako dočasný používateľ), ak je nastavené na user, nie je prihlásený, ak je nastavené na anon, alebo má právo bota, ak je nastavené na bot.

Jedna z nasledujúcich hodnôt: anon, bot, user
assertuser

Overiť, že aktuálny používateľ je uvedený používateľ.

Typ: používateľ, podľa ľubovoľného z používateľské meno a Dočasný používateľ
requestid

Akákoľvek tu zadaná hodnota bude zahrnutá do odpovede. Môže sa použiť na rozlíšenie požiadaviek.

servedby

Zahrnúť do výsledkov názov hostiteľa, ktorý obslúžil požiadavku.

Typ: logická hodnota (boolean) (podrobnosti)
curtimestamp

Zahrnúť do výsledku aktuálnu časovú pečiatku.

Typ: logická hodnota (boolean) (podrobnosti)
responselanginfo

Zahrnúť do výsledku jazyky použité pre uselang a errorlang.

Typ: logická hodnota (boolean) (podrobnosti)
origin

Pri prístupe k API pomocou AJAX požiadavky medzi doménami (CORS) nastavte tento parameter na pôvodnú doménu. Musí byť zahrnutý v každej predbežnej (pre-flight) požiadavke, a preto musí byť súčasťou URL požiadavky (nie tela POST).

Pri autentifikovaných požiadavkách sa musí presne zhodovať s jedným z pôvodov v hlavičke Origin, takže musí byť nastavený napríklad na https://en.wikipedia.org alebo https://meta.wikimedia.org. Ak sa tento parameter nezhoduje s hlavičkou Origin, vráti sa odpoveď 403. Ak sa tento parameter zhoduje s hlavičkou Origin a pôvod je povolený, nastavia sa hlavičky Access-Control-Allow-Origin a Access-Control-Allow-Credentials.

Pri neautentifikovaných požiadavkách zadajte hodnotu *. Tým sa nastaví hlavička Access-Control-Allow-Origin, ale Access-Control-Allow-Credentials bude false a všetky údaje špecifické pre používateľa budú obmedzené.

crossorigin

Pri prístupe k API pomocou AJAX požiadavky medzi doménami (CORS) a použití poskytovateľa relácie, ktorý je bezpečný proti útokom CSRF (cross-site request forgery), ako je napríklad OAuth, použite tento parameter namiesto origin=*, aby bola požiadavka autentifikovaná (t. j. nie odhlásená). Musí byť zahrnutý v každej predbežnej (pre-flight) požiadavke, a preto musí byť súčasťou URL požiadavky (nie tela POST).

Upozorňujeme, že väčšina poskytovateľov relácií vrátane štandardných relácií založených na cookies nepodporuje autentifikované CORS a nemožno ich použiť s týmto parametrom.

Typ: logická hodnota (boolean) (podrobnosti)
uselang

Jazyk, ktorý sa má použiť na preklady správ. action=query&meta=siteinfo&siprop=languages vráti zoznam kódov jazykov. Môžete zadať user, aby sa použil jazyk z nastavení aktuálneho používateľa, alebo content, aby sa použil jazyk obsahu tejto wiki.

Predvolené: user
variant

Variant jazyka. Funguje len vtedy, ak základný jazyk podporuje konverziu variantov.

errorformat

Formát, ktorý sa má použiť pre textový výstup upozornení a chýb

plaintext
Wikitext s odstránenými HTML značkami a nahradenými entitami.
wikitext
Neparsovaný wikitext.
html
HTML
raw
Kľúč správy a parametre.
none
Žiadny textový výstup, iba chybové kódy.
bc
Formát používaný pred MediaWiki 1.29. errorlang a errorsuselocal sa ignorujú.
Jedna z nasledujúcich hodnôt: bc, html, none, plaintext, raw, wikitext
Predvolené: bc
errorlang

Jazyk, ktorý sa má použiť pre upozornenia a chyby. action=query&meta=siteinfo&siprop=languages vráti zoznam kódov jazykov. Zadajte content, aby sa použil jazyk obsahu tejto wiki, alebo uselang, aby sa použila rovnaká hodnota ako v parametri uselang.

Predvolené: uselang
errorsuselocal

Ak je zadané, chybové texty budú používať lokálne prispôsobené správy z menného priestoru MediaWiki.

Typ: logická hodnota (boolean) (podrobnosti)

Poďakovanie

Vývojári API:

  • Yuri Astrakhan (tvorca, vedúci vývojár sep 2006 – sep 2007)
  • Roan Kattouw (vedúci vývojár sep 2007 – 2009)
  • Victor Vasiliev
  • Bryan Tong Minh
  • Sam Reed
  • Brad Jorsch (vedúci vývojár 2013 – 2020)

Svoje komentáre, návrhy a otázky posielajte na mediawiki-api@lists.wikimedia.org alebo nahláste chybu na https://phabricator.wikimedia.org/.