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.
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. - Verwendung eines Generators, anstatt für jedes Ergebnis einer anderen Anfrage eine neue 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.
Siehe auch
- API:Hauptseite - Die Schnellstart-Anleitung.
- Gewartet von MediaWiki Interfaces Team.
- Echtzeit-Chat (IRC): #mediawiki-core connect
- Problem-Tracker: Phabricator MediaWiki-Action-API (Problem melden)