API:Client-Code/Gold-Standard

Die Client-Bibliotheken der Action API, die auf API:Client-Code verfügbar sind, ermöglichen es Entwicklern, einfach und intuitiv mit der MediaWiki-API zu interagieren. Die derzeit aufgelisteten Bibliotheken unterscheiden sich erheblich hinsichtlich Möglichkeiten, Entwicklungsstatus und Qualität von Code/Dokumentation. Um es neuen Nutzern der API zu erleichtern, eine Bibliothek zu finden, die ihre Ansprüche erfüllt, führen wir einen "Gold-Standard" ein, der insbesondere qualitativ hochwertige, derzeit gewartete Bibliotheken kennzeichnet. Wir hoffen auch, dass der Standard Entwicklern von Bibliotheken dabei hilft, zu entscheiden, worauf sie ihre Anstrengungen fokussieren, sodass der von ihnen erstellte Code einfach von Experten und neuen Entwicklern genutzt werden kann.

Wir glauben, dass eine gute Client-Bibliothek einfach zu installieren, zu verstehen, zu nutzen, zu debuggen und zu verbessern sein sollte. Dafür ist eine zusätzliche Dokumentation ebenso wichtig wie eleganter Code. Sofern nichts anderes angegeben ist, gehören die Objekte unten zum "Gold-Standard": herausfordernd aber erreichbar. Die Objekte, die als "Platin-Standard" gekennzeichnet sind, zeigen, dass Bibliotheksentwickler weiter gegangen sind und über den "Gold-Standard" hinausgehen, was zu einer außergewöhnlichen Bibliothek führt.

Einfach zu installieren

• Installationsanleitungen sind korrekt und leicht zu finden
• Die Bibliothek ist über eine geeignete Paket-Bibliothek (PyPI, CPAN, npm, Maven, rubygems, etc.) als Paket zur Installation verfügbar
• Platin-Standard: Die Bibliothek ist über Linux-Distributionen als Paket verfügbar

Einfach zu verstehen

• Gut designt: Macht alle vorgesehenen API-Anrufe mit dem beabsichtigten Abstraktionsgrad verfügbar ohne Redundanzen
• Platin-Standard: Macht die Wikidata-API verfügbar
• Gut dokumentiert:
  • Code ist kommentiert und lesbar
  • Dokumentation ist umfassend, genau und leicht zu finden
  • Dokumentation gibt an, mit welchen MediaWiki-Versionen die Bibliothek kompatibel ist
  • Veraltete Funktionen sind eindeutig als solche markiert
  • Platin-Standard: Dokumentation ist für einen neuen Programmierer verständlich
• Code nutzt Idiome, die für die Sprache, in der die Bibliothek geschrieben ist, angemessen sind

Einfach zu nutzen

• Hat funktionierende, einfache und gut geschriebene Code-Beispiele für häufige Aufgaben
  • Demonstriert Abfragen
  • Demonstriert Bearbeitungen
• Geht mit Komplikationen und Eigenheiten der API um, sodass der Nutzer sich nicht darum kümmern muss:
  • Anmelden/Abmelden
  • Cookies
  • Tokens
  • Zur Fortsetzung von Abfragen wird das neue "continue" verwendet, nicht "query-continue"
  • Abfragen über HTTPS umfassen eine Zertifikatprüfung
• Die höfliche API-Nutzung wird durch Code-Beispiele und sinnvolle Voreinstellungen gefördert
  • gzip-Kompression wird standardmäßig verwendet
  • Beispiele zeigen, wie man einen aussagekräftigen User-Agent-Header erstellt und nutzt (wie in der User-Agent-Richtlinie)
  • Platin-Standard: Generiert eine einzigartige User-Agent-Zeichenkette anhand des angegebenen Namens / der Email-Adresse / des Orts des Repositoriums
  • Effiziente Nutzung von API-Anrufen
• Kann zusammen mit der letzten stabilen Version der Sprache genutzt werden, in der sie geschrieben ist (z.B. kompatibel mit Python 3)

Einfach zu debuggen

• Enthält Einheiten-Tests für die längsten und häufigsten modifizierten Funktionen der Bibliothek
• Platin-Standard: Einheiten-Tests für viele Code-Pfade existieren und werden gewartet
• Schreckliche Hacks / Beispiele extremer Klugheit sind in Kommentaren als solche eindeutig markiert
• Die Dokumentation verlinkt auf den relevanten Abschnitt, bzw. die Unterseite der API-Dokumentation

Einfach zu verbessern

• Bibliotheksentwickler sind reaktionsschnell und höflich und fördern eine durchdachte und integrative Gemeinschaft von Entwicklern und Nutzern
• Platin-Standard: Das Projekt setzt klare Erwartungen für das Verhalten in Räumen, in denen es zu Interaktionen mit Bezug zu dem Projekt kommt (Mailinglisten, IRC, Repositorien, Problemverfolgung). Es sollte:
  • Erwünschtes Verhalten festlegen
  • Beispiele für unerwünschtes und belästigendes Verhalten angeben
  • Erklären, wie diese Erwartungen durchgesetzt werden
• Pull-Anfragen werden innerhalb von 3 Wochen entweder akzeptiert oder mit einer Begründung abgelehnt (Platin-Standard: 3 Werktage)
• Auf Probleme/Fehler wird innerhalb von 3 Wochen reagiert (Platin-Standard: 3 Werktage) (sie werden jedoch nicht unbedingt behoben)
• Innerhalb von 3 Wochen (Platin-Standard: 3 Werktage) nach grundlegenden Änderungen an der API wird die Bibliothek aktualisiert und eine neue Version veröffentlicht
• Platin-Standard: Bibliotheksentwickler kontaktieren die Entwickler der MediaWiki-API und geben Rückmeldung zum Design und der Funktion der API
• Die Bibliothek gibt die Lizenz an, unter der sie veröffentlicht wurde