API:REST API

MediaWiki Core REST API vám umožňuje komunikovat s MediaWiki odesíláním požadavků HTTP na rest.php adresy URL. Rozhraní API můžete použít k vytváření aplikací a skriptů, které vyhledávají a zobrazují stránky wiki, získávají mediální soubory a prozkoumávají historii stránek.

Rychlý start

# Hledejte článek o Zemi na anglické Wikipedii $ curl "https://en.wikipedia.org/w/rest.php/v1/search/page?q=earth&limit=1"

Vyzkoušej to

Formát dat

Koncové body REST API vracejí data ve formátu JSON nebo HTML. Typ obsahu podporovaný každým koncovým bodem najdete v odkazu na rozhraní API.

Metody

Rozhraní API podporuje standardní metody požadavků HTTP.

GET	Načtení zdroje
HEAD	Vrácení HTTP hlavičky pro požadavek GET bez dat odpovědi
POST	Vytvoření zdroje
PUT	Aktualizace nebo vytvoření zdroj

Struktura URL

Koncové body API sdílejí konzistentní strukturu URL, která zahrnuje základní URL wiki, cestu skriptu wiki a verzi API.

# Struktura URL
[adresa URL projektu]/[cesta skriptu]/rest.php/v[číslo verze]/

# Příklad URL: Získejte historii hlavní stránky anglické Wikipedie
https://en.wikipedia.org/w/rest.php/v1/page/Main_Page/history

Verzování

MediaWiki REST API, navržené tak, aby poskytovalo vývojářům dlouhodobou stabilitu, je verzováno pomocí globálního čísla verze v cestě API (například: /v1/). Podle principů sémantického verzování se verze zvýší, když se koncový bod změní zpětně nekompatibilním způsobem, jako je odstranění vlastnosti odezvy nebo přidání požadovaného parametru. V rámci hlavní verze se API může změnit zpětně kompatibilními způsoby, jako je přidání vlastnosti odezvy nebo volitelného parametru požadavku.

/v1/ (nejnovější)	Dostupné na MediaWiki 1.35

Oprávnění a autorizace

REST API je navrženo pro použití s rozšířením OAuth pro ověřování a autorizaci uživatelů. Bez ohledu na metodu ověřování však API reaguje na přítomnost přihlášeného uživatele a vrací obsah odpovídající oprávněním tohoto uživatele.

Přístup k projektům Wikimedia pomocí REST API

REST API můžete použít pro přístup k Wikipedii, Wikislovníku a dalším projektům Wikimedia ve více jazycích. Úplný seznam adres URL projektů Wikimedia naleznete v matici stránek Meta-Wiki.

Limit požadavku

Neexistuje žádný pevný limit pro požadavky na API, ale váš klient může být zablokován, pokud ohrozíte stabilitu webu. Chcete-li zůstat v bezpečné míře požadavků, počkejte na dokončení každého požadavku, než odešlete další požadavek.

Identifikace klienta

Stránky Wikimedia vyžadují HTTP hlavičku User-Agent pro všechny požadavky API. To pomáhá identifikovat vaši aplikaci a zajišťuje, že vás v případě problému mohou kontaktovat správci systému. Klienti, kteří zadávají požadavky bez hlavičky User-Agent, mohou být bez upozornění blokováni IP adresou.

Záhlaví User-Agent může obsahovat uživatelskou stránku na místní wiki, uživatelskou stránku na související wiki používající syntaxi propojení interwiki, URL pro relevantní externí web nebo e-mailovou adresu.

# Preferovaný formát pro záhlaví User-Agent
<jméno klienta>/<verze> (<kontaktní údaje>) <název knihovny/rámce>/<verze>

Pokud voláte API z JavaScriptu založeného na prohlížeči, možná nebudete moci, v závislosti na prohlížeči, ovlivnit hlavičku User-Agent. Chcete-li to obejít, použijte hlavičku Api-User-Agent. Další informace naleznete v zásadách uživatelského agenta Meta-Wiki.

Autorizace

Chcete-li své aplikaci udělit oprávnění jednat jménem uživatele, postupujte podle příručky pro vývojáře OAuth, zaregistrujte svou aplikaci a odešlete požadavky pomocí tokenů OAuth.

Licence a ochranné známky

Obsah Wikimedia lze znovu použít v rámci podmínek stanovených příslušnou licencí. Licence se mohou v jednotlivých projektech lišit, takže informace o licencích a opětovném použití obsahu naleznete u jednotlivých projektů. Například anglický text Wikipedie lze použít za podmínek Creative Commons Attribution Share-Alike licence, zatímco mediální soubory na Wikimedia Commons jsou licencovány jednotlivě, jak je uvedeno na informační stránce souboru. Další informace o licencování a používání ochranných známek naleznete v pokynech pro vývojáře aplikací Meta-Wiki.

Omezení Wikidat

Zatímco REST API je k dispozici na projektech Wikimedia, není plně podporováno Wikidaty. V době psaní mohou některé koncové body vracet neočekávané chyby. Místo toho použijte Wikidata REST API.

Koncové body rozšíření

Rozšíření MediaWiki mohou zobrazovat koncové body API specifické pro rozšíření pomocí rozhraní REST API. Chcete-li začít, přečtěte si dokumenty rozšíření rozhraní REST API. Dokumentaci pro koncové body REST API poskytované rozšířeními naleznete v dokumentech rozšíření. Rozhraní rozšíření REST API je standardně dostupné na MediaWiki 1.34 přes $wgEnableRestAPI a na MediaWiki 1.35 a novější.

Srovnání API

API	Dostupnost	Základ URL	Příklad
Akce API MediaWiki	je součástí MediaWiki aktivováno na projektech Wikimedie	/api.php	https://cs.wikipedia.org/w/api.php?action=query&prop=info&titles=Země
REST API MediaWiki	je součástí MediaWiki 1.35+ aktivováno na projektech Wikimedie	/rest.php	https://cs.wikipedia.org/w/rest.php/v1/page/Země
Wikimedie REST API	není součástí MediaWiki k dispozici pouze pro projekty Wikimedie	/api/rest	https://cs.wikipedia.org/api/rest_v1/page/title/Země
Rozhraní API v komerčním měřítku pro projekty Wikimedie najdete na stránkách Wikimedia Enterprise

O těchto dokumentech

Tyto dokumenty jsou napsány ručně na základě zdrojového kódu MediaWiki Core. Opravy a doplnění jsou vítány Chcete-li sdílet výukový program nebo aplikaci, která používá MediaWiki REST API, přidejte odkaz na šablonu REST API.

Související odkazy

• REST API na Wikipedii
• Stránka iniciativy REST API
• Příručka:$wgRestPath

• Spravováno MediaWiki Interfaces Team.
• Živý chat (IRC): #mediawiki-core ^{připojit se}
• Nástroj pro sledování problémů: Phabricator MediaWiki-Action-API (nahlášení problému)