API:Etikette
| Diese Seite ist Teil der Dokumentation der MediaWiki action API. |
Diese Seite auf einen Blick:
|
Diese Seite enthält beste Vorgehensweisen, die bei der Nutzung der API befolgt werden sollten. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.
Verhalten
Anforderungslimit
Es gibt keine feste Beschränkung für Leseanfragen, aber sei rücksichtsvoll und versuche, eine Seite nicht herunterzufahren. Die meisten Systemadministratoren behalten sich das Recht vor, Benutzer kurzerhand zu sperren, wenn sie die Stabilität ihrer Seite gefährden.
Wenn du deine Abfragen nicht parallel, sondern nacheinander stellst, sodass eine neue Abfrage erst gestartet wird, wenn die vorherige beendet wurde, sollte dies zu einer sicheren Abfragerate führen. Außerdem wird empfohlen, dass du in einer Abfrage mehrere Objekte abfragst, indem du:
- Nutze das Pipe-Zeichen (
|), wenn dies möglich ist, z.B.titles=PageA|PageB|PageC, anstatt für jeden Titel eine eigene Abfrage zu erstellen. - Verwende einen Generator, anstatt für jedes Ergebnis eine eigene Anfrage zu stellen.
- Nutze die GZip-Kompression beim Stellen von API-Abfragen, indem du
Accept-Encoding: gzipsetzt, um die Bandbreiten-Nutzung zu reduzieren.
Abfragen, die Bearbeitungen verursachen, Statusänderungen verursachen oder anderweitig keine reinen Lese-Abfragen sind, unterliegen einem Limit. Das genaue Limit, das angewendet wird, kann von der Art der Aktion, deinen Benutzerrechten und der Konfiguration der Webseite, an die du die Abfrage richtest, abhängen. Du kannst herausfinden, welche Limits auf dich angewandt werden, indem du auf den API-Endpunkt action=query&meta=userinfo&uiprop=ratelimits zugreifst.
Wenn du das Abfragelimit erreichst, wirst du eine API-Fehlermeldung mit dem Fehlercode ratelimited erhalten. Wenn du diese Fehlermeldung erhältst, kannst du erneut versuchen, die Abfrage zu stellen, solltest jedoch die Zeit zwischen aufeinanderfolgenden Abfragen erhöhen. Eine verbreitete Strategie hierfür ist der Binary Exponential Backoff.
Parsing von Revisionen
Es ist möglich, durch Nutzung des Parameters revid Ergebnisse einer bestimmten Versionsnummer abzufragen, was jedoch eine erhebliche Serverbelastung verursacht.
Nutze den Parameter oldid, um eine bestimmte Version abzurufen. Zum Beispiel:
Der Parameter maxlag
Wenn deine Aufgabe nicht interaktiv ist, d.h. kein Benutzer auf das Ergebnis wartet, solltest du den Parameter maxlag nutzen.
Der Wert des Parameters maxlag sollte eine ganze Zahl von Sekunden sein.
Zum Beispiel:
Dies hält deinen Auftrag davon ab, zu laufen, während die Belastung der Server hoch ist. Höhere Werte bedeuten ein aggressiveres Verhalten, niedrigere Werte sind freundlicher.
Siehe Handbuch:Maxlag-Parameter für weitere Details.
Der User-Agent-Header
Es ist gute Praxis, einen beschreibenden User-Agent-Header zu setzen.
Nutze User-Agent: Clientname/ -version (Kontaktinformation, z.B. Benutzername, Email) Framework/Version..., um dies zu tun.
Zum Beispiel in PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Kopiere nicht einfach den User-Agent eines verbreiteten Web-Browsers. Dies stellt sicher, dass sich, wenn Probleme entstehen, einfach herausfinden lässt, wo diese entstehen.
Abhängig von deinem Browser kannst du möglicherweise nicht den User-Agent-Header beeinflussen, wenn du die API über ein browserbasiertes JavaScript ansteuerst.
Nutze den Api-User-Agent-Header, um dies zu umgehen.
Siehe m:User-Agent-Richtlinie für weitere Details.
Datenformate
Alle neuen API-Nutzer sollten JSON nutzen. Siehe API:Datenformate für weitere Details.
Performance
Das Herunterladen von Daten als Bulk über die Action API ist nicht immer sehr effizient. In Wikimedia-Wikis gibt es schnellere Wege, um Daten im Bulk zu erhalten, siehe m:Research:Data und wikitech:Portal:Data Services für weitere Details.
Weitere Hinweise
Wenn deine Anfragen Daten erhalten, die eine Zeit lang zwischengespeichert werden können, solltest du Maßnahmen ergreifen, um sie zwischenzuspeichern, damit du nicht immer wieder dieselben Daten abrufst. Manche Clients können die Daten selbst zwischenspeichern, aber bei anderen (insbesondere bei JavaScript-Clients) ist das nicht möglich.
Wenn du Daten von der Webservice-API liest, solltest du versuchen, GET-Anfragen zu verwenden, wenn dies möglich ist, nicht POST, da letzteres nicht zwischengespeichert werden kann.
In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see T91820.
Siehe auch
- Official guidelines about API usage on Wikimedia Foundation Governance wiki
- API:Hauptseite - Die Schnellstart-Anleitung.
- API:Ratelimit & API:Ratelimit/Wikimedia sites
- Gewartet von MediaWiki Interfaces Team.
- Echtzeit-Chat (IRC): #mediawiki-core connect
- Problem-Tracker: Phabricator MediaWiki-Action-API (Problem melden)