API:Etiquette/de

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. , anstatt für jeden Titel eine eigene Abfrage zu erstellen.
 * Verwendung eines, anstatt für jedes Ergebnis einer anderen Anfrage eine neue Anfrage zu stellen.


 * Nutze die GZip-Kompression beim Stellen von API-Abfragen, indem du  setzt, 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 mit dem Fehlercode   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  Ergebnisse einer bestimmten Versionsnummer abzufragen, was jedoch eine erhebliche Serverbelastung verursacht. Nutze den Parameter, 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  nutzen. Der Wert des Parameters  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 für weitere Details.



Der User-Agent-Header
Es ist gute Praxis, einen beschreibenden User-Agent-Header zu setzen. Nutze, um dies zu tun. Zum Beispiel in PHP:

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 -Header beeinflussen, wenn du die API über ein browserbasiertes JavaScript ansteuerst. Nutze den -Header, um dies zu umgehen.

Siehe m:User-Agent-Richtlinie für weitere Details.



Datenformate
Alle neuen API-Nutzer. Siehe 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.

Gemäß der HTTP-Spezifikation können POST-Anfragen nicht zwischengespeichert werden. Wenn du also Daten von der Webservice-API liest, solltest du GET-Anfragen verwenden, nicht POST.

Beachte auch, dass eine Anfrage nur dann aus dem Cache bedient werden kann, wenn die URL genau dieselbe ist. Wenn du eine Anfrage für  stellst und das Ergebnis im Cache speicherst, wird eine Anfrage für   nicht durch den Cache gehen - obwohl MediaWiki die gleichen Daten zurückgibt!

Du solltest darauf achten, die URLs, die du an den MediaWiki-Webservice sendest, zu normalisieren, damit du nicht durch leicht abweichende Benutzereingaben Zeit für unnötige HTTP-Anfragen verschwendest. Du kannst eine Liste von Seitentiteln normalisieren, indem du Duplikate entfernst und die Titel alphabetisch sortierst''. Ähnliche Techniken werden für verschiedene Arten von Daten funktionieren.



Siehe auch

 * - Die Schnellstart-Anleitung.