API:Klientský kód/zlatý standard

Klientské knihovny Action API dostupné na API:Kód klienta umožňují vývojářům snadno a intuitivně pracovat s MediaWiki API. Aktuálně uvedené knihovny se značně liší ve schopnostech, stavu údržby a kvalitě kódu/dokumentace. Abychom novým uživatelům API usnadnili hledání knihovny, která vyhovuje jejich potřebám, zavádíme "zlatý standard", který bude označovat zvláště kvalitní, aktuálně udržované knihovny. Doufáme také, že standard také pomůže vývojářům knihoven rozhodnout, jak zaměřit své úsilí, aby kód, který vytvářejí, mohli snadno používat zkušení i začínající vývojáři.

Věříme, že dobrá klientská knihovna by měla být snadno instalovatelná, snadno pochopitelná, snadno použitelná, snadno laditelná a snadno vylepšitelná. Přístupná dokumentace je jako taková stejně důležitá jako elegantní kód. Pokud není uvedeno jinak, níže uvedené položky patří ke "zlatému standardu": náročné, ale na dosah. Položky označené "platinový standard" naznačují, že vývojáři a správci knihoven šli nad rámec "zlatého standardu", což vedlo k výjimečné knihovně.

Snadná instalace

• Návod k instalaci je správný a snadno se hledá
• Knihovna je zabalena pro instalaci prostřednictvím příslušné knihovny balíčků (PyPI, CPAN, npm, Maven, rubygems atd.)
• Platinový standard: Knihovna je zabalena a zpřístupněna prostřednictvím distribucí Linuxu

Snadno pochopitelné

• Dobře navržený: Zpřístupňuje všechna zamýšlená volání API se zamýšlenou úrovní abstrakce bez redundance
• Platinový standard: Zpřístupňuje Wikidata API
• Dobře zdokumentované:
  • Kód je komentovaný a čitelný
  • Dokumentace je komplexní, přesná a snadno se hledá
  • Dokumentace určuje, se kterými verzemi MediaWiki je knihovna kompatibilní
  • Zastaralé funkce jsou jako takové jasně označeny
  • Platinový standard: Dokumentace je srozumitelná pro začínajícího programátora
• Kód používá idiomy vhodné pro jazyk, ve kterém je knihovna napsána

Snadné použití

• Má funkční, jednoduché a dobře napsané ukázky kódu pro běžné úkoly
  • Zobrazuje dotazy
  • Ukazuje úpravy
• Řeší komplikace nebo idiosynkrazie API, takže uživatel nemusí řešit:
  • Přihlášení/odhlášení
  • Cookies
  • Tokeny
  • Pokračování dotazů pomocí nového "continue" (pokračovat) a nikoli "query-continue" (dotaz-pokračovat)
  • Žádosti přes https, včetně ověření certifikátu
• Snadné použití API je podporováno prostřednictvím ukázek kódu a inteligentních výchozích nastavení
  • Ve výchozím nastavení se používá komprese gzip
  • Příklady ukazují, jak vytvořit a používat smysluplné záhlaví uživatelského agenta (jako v Zásadách uživatelského agenta)
  • Platinový standard: Generuje jedinečný řetězec user-agent jméno/e-mailová adresa/umístění úložiště
  • Efektivní využití volání API
• Lze použít s nejnovější stabilní verzí jazyka, ve kterém je napsán (např. kompatibilní s Python 3)

Snadné ladění

• Obsahuje unit testy pro nejdelší a nejčastěji upravované funkce v knihovně
• Platinový standard: Existují a jsou udržovány testy jednotek pro mnoho cest kódu
• Příšerné hacky/případy extrémní chytrosti jsou jako takové v komentářích jasně označeny
• Odkazy na dokumentaci na příslušnou sekci/podstránku dokumentace API

Snadno vylepšitelné

• Správci knihoven jsou vstřícní a zdvořilí a podporují promyšlenou a inkluzivní komunitu vývojářů a uživatelů
• Platinový standard: Projekt stanoví jasná očekávání pro chování pro prostory, kde dochází k interakcím souvisejícím s projektem (adresář, IRC, úložiště, sledování problémů). Mělo by:
  • Uveďte požadované postoje a chování
  • Uveďte příklady nevítaného a obtěžujícího chování
  • Upřesněte, jak budou tato očekávání vynucována
• Žádosti o stažení jsou buď přijaty, nebo zamítnuty s uvedením důvodu do 3 týdnů (Platinový standard: 3 pracovní dny)
• Na problémy/chyby se nějakým způsobem reaguje do 3 týdnů (Platinový standard: 3 pracovní dny) (ale nemusí být nutně opraveny)
• Knihovna je aktualizována a nová verze je vydána do 3 týdnů (Platinový standard: 3 pracovní dny), když budou provedeny změny API.
• Platinový standard: Správci knihoven kontaktují správce MediaWiki API se zpětnou vazbou na design a funkci API
• Knihovna specifikuje licenci, pod kterou je uvolněna