API:Etiquette/de

Diese Seite enthält beste Vorgehensweisen, die bei der Nutzung der API befolgt werden sollten.

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.
 * Nutze einen, anstatt für jedes Ergebnis aus einer anderen Abfrage eine Abfrage zu erstellen.


 * 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 $1 und $2 für weitere Details. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.

Other notes
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. If you make a request for, and cache the result, then a request for   will not go through the cache — even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.

Siehe auch

 * - Die Schnellstart-Anleitung.